1989_TI_TIGA 340_Interface_Users_Guide 1989 TI TIGA 340 Interface Users Guide
User Manual: 1989_TI_TIGA-340_Interface_Users_Guide
Open the PDF directly: View PDF 
.
Page Count: 374
| Download | |
| Open PDF In Browser | View PDF |
,111 TEXAS
lNSTRuM ENTS
TIGA·340™ Interface
Texas Instruments Graphics Architecture
Graphics Products
TIGA·340™ Interface
Texas Instruments
Graphics Architecture
User's Guide
•
. TEXAS
INSTRUMENTS
IMPORTANT NOTICE
Texas Instruments (TI) reserves the right to make changes to or to discontinue
any semiconductor product or service identified in this publication without notice.
TI advises its customers to obtain the latest version of the relevant information
to verify, before placing orders, that the information being relied upon is current.
TI warrants performance of its semiconductor products to current specifications
in accordance with Tl's standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Unless mandated by government requirements, specific testing of all parameters of
each device is not necessarily performed.
TI assumes no liability for TI applications assistance, customer product design,
software performance, or infringement of patents or services described herein.
Nor does TI warrant or represent that license, either express or implied, is granted
under any patent right, copyright, mask work right, or other intellectual property
right ofTI covering or relating to any combination, machine, or process in which
such semiconductor products or services might be or are used.
TRADEMARKS
TIGA and TIGA-340 are trademarks of Texas Instruments Incorporated.
ADI and AutoCAD are trademarks of Autodesk Inc.
DGIS is a trademark of Graphic Software Systems, Inc.
GEM is a trademark of Digital Research Inc.
MS-Windows, PM, MS-DOS, and CodeView are trademarks of Microsoft Corp.
Macintosh is a trademark of Apple Computer Corp.
NEC is a trademark of NEC Corp.
PC-DOS and PGA are trademarks of IBM Corp.
Sony is a trademark of Sony Corp.
Preface
Read This First
How to Use This Manual
This document contains the following chapters:
Chapter 1
Introduction
Introduces the TIGA-340 Interface, its features and architecture.
Chapter 2
Getting Started
Contains instructions to install TIGA on a PC and to run a demonstration program.
Chapter 3
TIGA Application Interface
Describes the application interface and lists all TIGA primitive instructions.
Chapter 4
Extensibility Through the User Library
Describes how to extend TIGA by adding your own functions; also describes
the command processing entry points of the communication driver.
Appendix A TIGA Data Structures
Describes the data structures used in TIGA.
Appendix B Graphics Output Primitives
Describes the assumptions made and conventions adopted for the drawing
primitives.
Appendix C TIGA Reserved Symbols
Describes the function names reserved for internal use of TIGA.
Appendix D Porting Guide
Describes the procedure to port TIGA to any TMS340-based graphics
board.
Appendix E Debugger Support for TIGA
Contains the initial TIGA debugger routines.
Appendix F Glossary
Contains the definitions of TIGA-specific and TIGA-related terms and acronyms.
iii
Read This First
Related Documentation
The following TMS3401 0 documents are available from Texas Instruments:
Q The TMS34010 C Compiler User's Guide (literature number
SPVU005) tells you how to use the TMS3401 0 C Compiler. This C compiler accepts standard Kernighan and Ritchie C source code and produces TMS3401 0 assembly language source code. We suggest that
you use The C Programming Language book (by Brian W. Kernighan
and Dennis M. Ritchie) as a companion to the TMS34010 C Compiler
User's Guide.
Q The TMS34010 Assembly Language Tools User's Guide (literature
number SPVU004) describes common object file format, assembler directives, macro language, and assembler, linker, arch ive r, simulator,
and object format converter operation.
Q The TMS34010 Data Sheet {literature number SPVS002) contains the
recommended operating conditions, electrical specifications, and timing characteristics of the TMS34010.
Q
The TMS34010 User's Guide (literature number SPVU001) discusses
hardware aspects of the TMS3401 0, such as pin functions, architecture, stack operation, and interfaces, and contains the TMS3401 0 instruction set.
You may also find the following documentation useful:
Kernighan, Brian, and Dennis Ritchie. The C Programming Language. Englewood Cliffs, New Jersey: Prentice-Hall,1978.
Newman W.M., and R. F. Sproull. Principles of Interactive Computer Graphics. 2nd ed. New York: McGraw-Hili, 1979.
iv
Preface
Read This First
Style and Symbol Conventions
This document uses the following conventions:
a
a
TIGA primitive function names are shown in bold face lettering.
Parameters for the TIGA functions are shown in program font (Courier). For example, the TIGA function draw_line has parameters xl,
yl, x2, y2.
a
Program examples and filenames (example: TIGALNK. EXE) are shown
in program font. Here is an example program:
*include
main()
(
short module;
/* initialize TIGA */
if (!set_videomode(TIGA, INIT»
{
printf("Fatal Error - TIGA not installed\n");
exit(O);
/* attempt to install module */
if «module = install_rIm ("EXAMPLE") ) < 0 )
{
printf("Fatal Error - couldn't install Example RLM\n");
printf("Error code = %d\n", module);
exit(O);
/* code to invoke the module functions */
set_videomode(PREVIOUS, INIT);
a
In syntax descriptions, the instruction, command, or directive is in a
bold face font with parameters in italics. Portions of a syntax in bold
face (including quote marks) should be entered as shown. Portions of
a syntax in italics describe the type of information that you provide.
Square brackets identify optional information:
mg2tiga
MGfont
TIGA font
[ "facename"]
v
vi
Preface
)IT
:::: ::m
E
?MIl!
it li!
PH!
mw
II
::
i:
:
If
Contents
mn
1t
1
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
1.1
Developer's Kits '" ..... , . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
1.2
Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
1.3
Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
1.4
Extensibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
1-1
1-2
1-3
1-4
1-6
2
Getting Started ................................................ 2-1
2.1
System Requirements ...................................... 2-2
2.1.1 TIGA Driver Developer's Kit (DDK) System Requirements . . .. 2-2
2.1.2 TIGA Software Porting Kit (SPK) System Requirements ..... 2-2
Installing TIGA on Your System ............................... 2-4
2.2
2.2.1
Driver Developer's Kit (DDK) Subdirectories. . . . . . . . . . . . . .. 2-5
2.2.2 Software Porting Kit (SPK) Subdirectories ................ 2-5
2.2.3 TIGA Demonstrations and Example Subdirectories ......... 2-6
2.2.4 Running a TIGA Demonstration ........................ 2-6
2.2.5 TIGA Include Files .................................. , 2-8
2.3
Modifying Autoexec and the Environment ....................... 2-9
2.4
Running the TIGA Driver ................................... 2-10
2.5
The TIGA Environment Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 2-11
2.6
TIGA Utility Programs ...................................... 2-12
2.6.1
cc Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 2-12
2.6.2 cltiga Batch File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 2-12
2.6.3 mg2tiga Utility ..................................... 2-13
2.6.4 tigamode Utility .................................... 2-16
Non-TIGA Development Utility Programs ....................... 2-17
2.7
TIGA Syntax and Programming Examples ...................... 2-18
2.8
3
TIGA Application Interface . ......................................
3.1
Base Set of TIGA Primitives ................................. ,
3.2
Summary Table of Functions by Functional Group. . . . . . . . . . . . . . . ..
3.2.1
Graphics System Initialization Functions ................. ,
3.2.2 Clear Functions .................................... ,
3.2.3 Graphics Attribute Control Functions. . . . . . . . . . . . . . . . . . . ..
3-1
3-2
3-3
3-3
3-4
3-5
vii
Contents
3.3
4
viii
3.2.4 Palette Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-6
3.2.5 Graphics Output Functions ............................ 3-7
3.2.6 Poly Drawing Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-8
3.2.7 Workspace Functions ................................ 3-8
3.2.8 Pixel Array Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-8
3.2.9 Text Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-9
3.2.10 Cursor Functions ................................... 3-10
3.2.11 Graphics Utility Functions ............................ 3-10
3.2.12 Pointer-Based Memory Management Functions . . . . . . . . . .. 3-11
3.2.13 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-11
3.2.14 Extensibility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-12
Alphabetical List of Functions .............................. " 3-13
Extensibility Through the User Library. . . . . . . . . . . . . . . . . . . . . . . . . . . .. 4-1
4.1
Dynamic Load Module ...................................... 4-2
4.1.1
Relocatable Load Modules ............................ 4-2
4.1.2 Absolute Load Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 4-2
4.2
Generating a Dynamic Load Module ........................... 4-4
4.2.1 TIGAEXT Section ................................... 4-4
4.2.2 The TIGAISR Section ................................ 4-5
4.2.3 Linking the Code and Special Sections into an RLM . . . . . . . .. 4-5
Installing a Dynamic Load Module ............................. 4-7
4.3
4.3.1
Installing a Relocatable Load Module .................... 4-7
4.3.2 Installing an Absolute Load Module. . . . . . . . . . . . . . . . . . . . .. 4-8
4.4
Invoking Functions in a Dynamic Load Module .................. 4-10
4.4.1
Command Number Format ........................... 4-10
4.4.2 Using Macros in Command Number Definitions ......... " 4-11
4.4.3 Passing Parameters to the TIGA Function ............... 4-12
4.5
C-Packet Mode ...................................' ...... " 4-13
4.5.1 The Type of Call ................................... 4-13
4.5.2 The Command Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 4-13
4.5.3 Description of Function Arguments ..................... 4-14
4.5.4 C-Packet Examples ................................ 4-14
4.5.5 Overflow of the Command Buffer ...................... 4-16
4.6
Direct Mode ............................................ 4-18
4.6.1
Standard Command Entry Point ....................... 4-18
4.6.2 Standard Command Entry Point with Return. . . . . . . . . . . . .. 4-20
4.6.3 Standard Memory Send Command Entry Point. . . . . . . . . . .. 4-21
4.6.4 Standard Memory Return Command Entry Point .......... 4-23
4.6.5 Standard String Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . .. 4-24
4.6.6 Altered Memory Return Command Entry Point .......... " 4-24
Table of Contents
Contents
4.7
4.8
4.9
4.10
A
4.6.7 SendlReturn Memory Command Entry Point .............
4.6.8 Mixed Immediate and Pointer Command Entry Point .......
4.6.9 Mixed Immediate and Pointer Command Entry Point wi Return
4.6.10 Poly Function Command . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.6.11 Immediate and Poly Data Entry Point ...................
Downloaded Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.7.1
Register Usage Conventions . . . . . . . . . . . . . . . . . . . . . . . . ..
4.7.2 TIGA Graphics Manager System Parameters .............
Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.8.1
Stars Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.8.2 Curves Example Program ............................
4.8.3 ADI Driver Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Installing Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.9.1
Clock Example of Using Interrupts .....................
4.9.2 Ball Example Using Interrupts . . . . . . . . . . . . . . . . . . . . . . . ..
The TIGA Linking Loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.10.1 Ica - Create Absolute Load Module ....................
4.10.2 Ics - Create External Symbol Table ....................
4.10.3 lec - Error Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
4.10.4 Ifs - Flush External Symbol Table . . . . . . . . . . . . . . . . . . . . ..
4.10.5 lIa - Load and Install an Absolute Load Module ...........
4.10.6 Ilr - Load and Install a Relocatable Load Module ..........
4.10.7 Ilx - Load and Execute a COFF File I Execute TIGA GM . . ..
4-24
4-25
4-25
4-26
4-28
4-32
4-33
4-35
4-36
4-36
4-40
4-43
4-44
4-45
4-46
4-47
4-48
4-48
4-48
4-49
4-49
4-49
4-49
TIGA Data Structures ........................................... A-1
A.1
Integral Data Types ..................•..................... A-2
A.2
CONFIG Structure ......................................... A-3
A.3
CURSOR Structure ........................................ A-5
ENVIRONMENT Structure ................................... A-6
A.4
A.5
FONTINFO Structure ....................................... A-7
MODEINFO Structure ..................................... A-11
A.6
A.7
MONITORINFO Structure .................................. A-13
A.8
OFFSCREEN Structure .................................... A-14
PAGE Structure .......................................... A-15
A.9
A.10 PALET Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. A-16
A.11 PATIERN Structure ....................................... A-17
B·· Graphics Output Primitives ......................................
B.1
Categories of Graphics Output Primitives .......................
B.2
Fill Patterns ..............................................
B.3
Mapping Pixels to XV Coordinates ........................ .- . . ..
B-1
B-2
B-4
B-5
ix
Contents
B.4
B.5
B.6
B.7
Area Filling Conventions ....................................
Vector Drawing Conventions .................................
Drawing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Color Selection ............................................
B-6
B-7
B-8
B-9
C
TIGA Reserved Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
C.1
Reserved Functions ........................................
C.2 TIGA Core Primitive Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3 TIGA Extended Primitive Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C-1
C-2
C-3
C-5
o
Porting TIGA .................................................. 0-1
0.1
Porting the Communication Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0-2
0.1.1 Modifying the sdbdefs.inc File ........................ " 0-2
0.1.2 Modifying the oemdata.asm File ........................ 0-4
0.1.3 Defining the Mode-Specific Information. . . . . . . . . . . . . . . . . .. 0-4
0.1.4 Defining the Mode Label and Setup_Struc Structure ........ 0-5
0.1.5 Defining the Mode_Struc Structure ...................... 0-5
0.1.6 Defining the MonitoUnfo Structure . . . . . . . . . . . . . . . . . . . . . . 0-6
0.1.7 Defining the Page_Info Structure ....................... 0-6
0.1.8 Defining the Off_Screen Structure ..................... " 0-7
0.1.9 Defining OEM-Specific Data ........................... 0-8
0.1.10 Completing Modifications to oemdata.asm ................ 0-8
0.1.11 Modifying the oeminit.asm File ......................... 0-9
0.1.12 Modifying the OEM_lnit Function ...•................... 0-9
0.1.13 Modifying the OEM_Sense Function . . . . . . . . . . . . . . . . . . .. 0-10
0.1.14 Modifying the MonitoUnit Function. . . . . . . . . . . . . . . . . . . .. 0-10
0.1.15 Modifying the Video_Enable Function .................. , 0-10
0.1.16 Modifying the setvideo.asm File ....................... 0-10
0.1.17 Miscellaneous Communication Driver Porting Issues ....... 0-11
0.1.18 Default Timeout for gm_is_alive Function ... . . . . . . . . . . . .. 0-11
0.1.19 Using Boards with Multi-Addressable Host Port Locations ... 0-11
0.1.20 Rebuilding the Communication Driver . . . . . . . . . . . . . . . . . .. 0-13
0.2 Porting the Graphics Manager ............................... 0-14
0.2.1 Video Memory Initialization Functions ................... 0-14
0.2.2 Palette-Specific Functions ............................ 0-15
0.2.3 Configuration Functions .............................. 0-16
0.2.4 Miscellaneous Functions ............................. 0-17
0.2.5 Rebuilding the Graphics Manager ...................... 0-19
0.3 Verifying Correct Operation ................................. 0-21
0.4 Debugging Your Port ...................................... 0-22
E
Debugger Support for TIGA ...................................... E-1
0.1
TIGA Debugger Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. E-2
x
Table of Contents
Contents
0.2
F
Compatibility Functions .................................... E-12
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. F-1
xi
Figures
1-1.
1-2.
4-1.
4-2.
4--3.
4-4.
4-5.
4-6.
A-1.
B-1.
B-2.
B-3.
8-4.
xii
1-4
Block Diagram
Primitive Configuration Options ................................. 1-6
Command Number Format .................................... 4-10
Data Structure of dm_cmd .................................... 4-19
Data Structure of dmJ)snd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 4-21
Data Structure Before Invoking dmJ)get ....•.................... 4-23
Data Structure After Invoking dm_pget . . . . . . . . . . . . . . . . . . . . . . . . . .. 4-23
Data Structure of dmJ)oly .................................... 4-26
Bitmap Font Format ......................................... A-10
A 16 x 16 Pattern ............................................ B-4
Rectangle Fill ............................................... B-5
Polygon Fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. B-6
Polygon Outline ............................................. B-7
Table of Contents
Tables
~jli
.....
him
It
:E:::
3-1 .
3-2.
B-1.
8-2.
;
Pixel Processing Options ..................................... 3-74
Pixel Processing Options .................................... 3-165
List of Function Types and Drawing Styles . . . . . . . . . . . . . . . . . . . . . . . .. 8-2
Checklist of Available Figure Types and Drawing Styles .............. 8-3
xiii
Exameles
Example 4-1. . .................................................... 4-7
Example 4-2. . .................................................... 4-8
Example 4-3. .................................................... 4-27
xiv
Table of Contents
Chapter 1
Introduction
fa
m:m: ::
m:
:S!
1m::::: ill
:
This user's guide describes the TIGA-340™ (Texas Instruments Graphics
Architecture), a software interface that standardizes communication between application software and all TMS340 family-based hardware for IBMcompatible personal computers. TIGA divides tasks between the TMS340
processor and the BOxB6 host to improve application performance.
Section
Page
1.1 Developer's Kits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 1-2
1.2 Features ......................................... 1-3
1.3 Architecture....................................... 1-4
1.4 Extensibility....................................... 1-6
The TIGA interface standard simplifies the development of portable applications and application drivers to the diverse range of TMS340-based systems. TIGA can be extended so that software developers can customize
TIGA-340 to a specific application and so that hardware developers can provide a simple interface to specific target features.
TIGA contains a low-level communication interface designed so that other
standards such as MS-Windows, Presentation Manager (PM), DGIS, GEM,
CGI, and PGA, can run through the interface with no performance penalty.
Essentially, TIGA replaces custom communication routines in other software interfaces with a single standard set of host-to-TMS340 communication routines.
1-1
1111
Developer's Kits
1.1
Developer's Kits
This user's guide supports two basic TIGA developer's kits, the Driver Developer's Kit (DDK) and the Software Porting Kit (SPK). A third developer's kit, the Software Developer's Kit (SDK), includes the DDK as a subset.
a
DDK: The Driver Developer's Kit (TI part number TMS340 DDK-PC)
The TIGA-340 DDK provides software designers with the tools required
to produce TIGA-compatible applications. These tools include a copy of
the TIGA-340 interface, which runs on the TMS3401 0 Software Development Board, a user's guide, utilities, an AutoCAD release 9 sample
driver, and several TIGA-compatible example programs. With these
tools a programmer can modify existing applications to run with the
TIGA-340 interface or develop new TIGA-compatible applications. The
development of TIGA-compatible applications is easy because the
tools in the kit are designed to work with the industry-standard Microsoft
C development tools and debugging environments.
a
SPK: The Software Porting Kit (TI part number TMS340SPK-PC)
The SPK helps hardware manufacturers and software operating environment developers make their TMS340-based systems TIGA-compatible.The SDK, described below, is included as a subset to this kit.
The SPK contains everything in the DDK plus all source code required
to port the TIGA-340 interface to any TMS340 system, allowing all
TIGA-compatible applications to run on that system. TMS340 source
and 8086 object codes for a TIGA-compatible Windows/286 driver are
also included.
a
SDK: The Software
TMS340SDK-PC)
Developer's
Kit
(TI
part
number
The SDK is for those who want to develop direct TMS3401 0 code or
custom, downloadable extensions to TIGA. In addition to the DDK, it includes TI's TMS3401 0 C Compiler, Assembler, Bitmap Font, and Mathl
Graphics source code libraries.
1-2
Introduction
Features
1.2 Features
These are the key application-related features of the TIGA interface standard:
Applications run faster TIGA-340 provides the application writer with a
dual-processor environment. This enables the
tasks in the application to be run in parallel by
partitioning them between the host and the
TMS340 processors. The TIGA-340 interface is
optimized to provide high-speed communications between the host and the TMS340
family processors and to minimize the
overhead in the processing of TIGA commands.
Easy to use
TIGA-340 provides applications with a base set
of graphics primitives, with all the support
required forthe graphics subsystem. TIGA-340
is compatible with the Microsoft C environment,
and Microsoft development tools can be used
for debugging the application.
Extensible
Where an application requires graphics
functions that are not available in the TIGA base
set of primitives, the application writer can
develop user-extended primitives using
TMS340 C, assembly language, or a mixture of
the two. These user-extended primitives can be
downloaded at runtime during the application
initialization.
Hardware independent
Inquiry functions are provided that enable the
application to determine the resolution, pixel
size, etc., of the graphics subsystem and to
adapt itself to the board on which it runs.
1-3
Architecture
1.3 Architecture
Figure 1-1 shows a block diagram of the TIGA-340 interface, illustrating the
communication between the host routines and the TMS340 family processor routines.
As Figure 1-1 shows, the TIGA standard consists of four components:
1) Application Interface (AI)
2) Communication Driver (CD)
3) Graphics Manager (GM)
4) TIGA Extensions
Figure 1-1. Block Diagram
GRAPHICS MANAGER
rL _
Application
APPLICATION-l
-iNTERFACe.. _.J
•
COMMUNICATION
DRIVER (TSR)
Host PC
A
/
\
t..
TIGA-340'\
InterfaCe,;
Command
Executive
!
TIGA Primitives
User-Extended
Primitives
TMS340 Board
The Application Interface (AI) is linked in with a TIGA Application. The AI
consists of header files that reference TIGA function and type definitions,
which may be used in the application, and of a library that the application
links to when it is created. The AI does not actually contain the routines that
interface to the TMS340 processor; these routines are contained in the communication driver.
The Communication Driver (CD) is a Terminate-and-Stay-Resident (TSR)
program that runs on a host PC. The CD is specific to the TMS340 board
,and is ported to it by a board manufacturer. A manufacturer ships the CD
with the board; the CD is in a file called TIGACD • EXE. This file can be invoked
by the user directly from the command line or placed in the AUTOEXEC • BAT
file to be executed at startup. The CD contains the functions used to communicate between the host and the TMS340 board. These functions are in1-4
Introduction
Architecture
voked via calls in the AI made by the application. These communication
functions take care of the host side hardware-dependent portion of TIGA,
considering such things as whether the TMS340 board is memory-mapped
or I/O-mapped.
The Graphics Manager (GM) is a program that runs on the TMS340 board
and is specific to the board that it resides on. It consists of a command executive that handles the TMS340 side of the communications with the host,
and a set of standard primitives that perform graphics operations. The GM
typically resides in RAM on the board (although this is not a requirement)
and therefore must be loaded onto the board after power-up. There are two
mechanisms for doing this. TIGA comes with a linking loader TIGALNK. EXE,
which loads the GM explicitly by invoking it with the -lx (Load and eXecute)
flag. Alternately, the communication driver routines can sense whether the
GM is running; when the application makes its first AI call, it detects if AI is
not running and loads it.
TIGA contains a set of primitives to perform a wide range of graphics operations.The set of primitives can be extended by downloading the application
functions onto the TMS340 system. These downloaded functions may be
written using either the TMS340 C or assembly languages. Downloading
functions can decrease the host-TMS340 processor communications time
and thus improve the performance of the application.
The host application invokes most of the TIGA functions on the TMS340
processor by downloading the parameters of the function, along with a command number, into one of several communication buffers. The command
number is an identifierforthe function to be executed. The command executive, which forms part of the GM, determines which function is to be invoked
and calls it with the parameters that have been passed to it. Because there
are several buffers, the host downloads data into one buffer while the
TMS340 is executing data from another. This parallelism produces significant speed improvement over the host performing the graphics manipulation directly.
1-5
Extensibility
1.4
Extensibility
Graphics standards before TIGA limited the software developer by providing a fixed set of graphics drawing primitives. In the rapidly changing graphics market, a fixed set of primitives is unacceptable. During the development
of the TIGA graphics interface, incorporating extensibility into the standard
was a major design goal.
TIGA's functionality can be extended by adding or manipulating its user library collection of C-callable routines. Figure 1-2 shows the configuration
options for TIGA primitives.
Figure 1-2. Primitive Configuration Options
Base Set of TIGA
Primitives
Hardware and Software Developer Options
or
TIGA Extended
Primitives
(example: patnfllLoval)
TIGA Extended
Primitives
Core Primitives (example:
gsp_malloc)
Core Primitives
Core Primitives
TIGA-compatible applications can be developed using the base set of primitives provided by the TIGA-340 Interface (as shown in the left hand side of
Figure 1-2). These TIGA primitives include the core primitives, which are always available to the application, and the TIGA extended primitives, which
are loaded if the application requires them.The set of graphics primitives
and the performance of the TMS340 processor give many applications an
acceptable level of graphics performance. However, an application has the
ability to improve this performance by downloading user-extended primitives. The user-extended primitives can be downloaded to be used in addi1-6
Introduction
Extensibility
~::::::~»-::~-:::::='iH_·i·:::==-=-=-=-=-_·w.~s-»:>:>..;--.«;:::-M:Wh.~w.:''''''~W:::::::_'''_=_'::;:;:;.~::;:~.;s:;.~..w.@":::::::::;~~~~':(:i:;%~:::::;::!::;::S
tion to or instead of the TIGA extended primitives (as shown on the righthand side of Figure 1-2).
A hardware developer can implement the same concept of adding primitives. For example, if the developer of a TMS340-based graphics system
incorporates hardware in addition to the TMS340 processor, access to this
hardware can be provided through the TIGA interface. The access is accomplished by developing a set of user-extended primitives which use the
additional hardware functionality. Thus, the TIGA-340 interface provides a
standard programming platform forthe software written by the hardware developer using these user-extended primitives.
1-7
1-8
Introduction
Chapter 2
Getting Started
!11m
Imll
IT
I
mil
This chapter contains instructions for installing TIGA on your system:
Section
Page
2.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 2-2
2.2 Installing TIGA on your System . . . . . . . . . . . . . . . . . . . . . . .. 2-4
2.3 Modifying the Autoexec and the Environment. . . . . . . . . . . .. 2-9
2.4 Running the TIGA Driver ............................. 2-10
2.5 The TIGA Environment Variable ....................... 2-11
2.6 TIGA Utility Programs ............................... 2-12
2.7 Required Non-TIGA Development Utility Programs ........ 2-17
2.8 TIGA Syntax and Programming Examples ............... 2-18
2-1
System Requirements
2.1
System Requirements
To ensure proper installation and operation of TIGA, your system must meet
certain software and hardware minimum requirements. Consult the following sections for a list of these requirements, depending on the TIGA kit you
are installing.
2.1.1
TIGA Driver Developer's Kit (DDK) System Requirements
~
IBM PC, XT, AT or 100% compatible (hard disk required)
~
640KRAM
~
LIM expanded memory plus expanded memory manager (for ADI driver
only)
~
Texas Instruments TMS3401 0 Software Development Board (SOB)
~
MS-DOS or PC-DOS, version 2.13 or above
Q
Microsoft Macro Assembler, version 5.0 or above (if developing assembler-based applications/drivers)
~
Microsoft C Compiler, version 5.0 or above (if developing C applications)
~
TMS34010 C Compiler and assembly-language tools, version 3.0 or
above (if writing user-extended functions)
Note:
The current version of TIGA supplied with the DDK is designed to run only
on a Texas Instruments software development board (SOB). Pricing and ordering information for the SOB is available from your local Texas Instruments Sales Office.
2.1.2 TIGA Software Porting Kit (SPK) System Requirements
Q
IBM PC,XT,AT or 100% compatible (hard disk required)
~
640KRAM
~
LIM expanded memory plus expanded memory manager (for ADI driver
only)
Q Texas Instruments TMS34010 Software Development Board (SOB)
(Only if you are not porting TIGA to a different board)
~
2-2
MS-DOS or PC-DOS, version 2.13 or above
Getting Started
System Requirements
I:l
I:l
I:l
Microsoft Macro Assembler, version 5.0 or above
Microsoft C Compiler, version 5.0 or above (if developing C applications)
TMS34010 C Compiler and assembly-language tools, version 3.0 or
above (if writing user extended functions and/or if porting TIGA to a different board)
Note:
The current version of TIGA supplied with the SPK is designed to run on
a Texas Instruments software development board. However, all software
necessary to port TIGA to a different TMS340 board is included in in the
SPK. Consult Appendix 0 for information on how to port TIGA to a different
TMS340 board.
2-3
Installing TlGA on your System
2.2
Installing TIGAon Your System
Note:
If you have an earlier version of TIGA on your system, be aware that the
TIGA installation procedure overwrites same-named files in the tiga and
tigapgms directories. For this reason, files of previous versions of TIGA
should be backed up, if needed, before proceeding with the new TIGA installation.
Both the TIGA DDK and SPK kits have an automated installation program
to aid in installing TIGA on your system. In general, the installation procedure for the DDK and the SPK are the same.
The DDK package is a subset of the SPK; the SPK package contains all
of the files in the DDK plus additional files required for porting purposes.
Therefore, if you have both the DDK and the SPK packages, install only the
SPK on your system.
Follow these instructions to install your TIGA kit:
Step 1: Place disk #1 (DDK #1 or SPK #1) of your TIGA kit into drive A:
Step 2: If A: is not your current drive, enter
A:
8
at the MS-DOS prompt.
Step 3: Make sure you are at the root directory of A:. If you are not sure,
enter cd\ 8 at the MS-DOS prompt.
Step 4: Enter setup dri ve: Ell where drive:designates your destination
drive (hard disk). For example, if you want to install TIGA on your
C: hard disk, enter setup c: 8.
Step 5: Follow the instructions displayed on the screen to complete installation.
During installation, you have the option of installing a collection of TIGAcompatible examples and demonstrations. It is recommended that these
examples be installed because they are referenced as coding examples in
this guide.
The installation of your TIGA kit creates a number of subdirectories on your
destination drive. Consult one of the following two sections (depending on
the TIGA kit you installed) for information describing these subdirectories
and the files contained within them.
2-4
Getting Started
Installing TIGA on your System
=::!~~
2.2.1
Driver Developer's Kit (DDK) Subdirectories
Installing the DDK on your system creates the following subdirectories:
Subdirectory
Description
TIGA root directory, TIGA drivers, system files, and
utility programs
\tiga\ai
Application interface library
\tiga \grn\extprims Extended primitives source code archive
\tiga\include
Include files
\tigapgrns
TIGA compatible examples and demonstrations
(see Section 2.2.3 for more information)
\tiga
The \ tiga \gm\extprims directory contains the self-extracting archive file
extprims. exe. This archive contains source for every extended function
available within TIGA. It enables you to choose the extended functions you
need, link them with your specific user extensions, and create a custom
TIGA dynamic load module with the TMS340 functions that your application
or driver requires. To unarchive the source files contained in this archive, enter extprims
from within this directory.
8
2.2.2
Software Porting Kit (SPK) Subdirectories
Installing the DDK on your system creates the following subdirectories:
Subdirectory
Description
TIGA root directory, TIGA drivers, system
files, and utility programs
\tiga\ai
Application interface library and source
\ tiga \cd
TIGA communication driver source
\tiga\gm
TIGA graphics manager root directory
\ tiga \gm\corprims TIGA graphics manager core primitives
\ tiga \gm\extprims TIGA graphics manager extended primitives
\tiga\gm\sdb
TIGA graphics manager SDB specific files
\tiga\include
Include files
\ tigapgrns
TIGA compatible examples and demonstrations
(see Section 2.2.3 for more information)
\tiga
2-5
Installing TIGA on your System
2.2.3 TIGA Demonstrations and Example Subdirectories
During installation, you have the option of installing a collection of TIGA
compatible demonstrations and examples. When installed, the following directories are created on the destination drive:
\tigapgms
\tigapgms\adi
\tigapgms\asmtst
\tigapgms\ball
\tigapgms\clock
\tigapgms\curves
\tigapgms\examples
\tigapgms\flysim
\tigapgms\stars
\tigapgms\tests
\tigapgms\tigademo
\tigapgms\tigamode
\tigapgms\tigalogo
\tigapgms\windows
TIGA compatible examples and demonstrations
TIGA compatible AutoCAD example driver
Assembly language application example
Interrupt example using graphics
Downloaded interrupt function example
Floating-point example
Examples supplied in Chapter 3 of this guide.
3-D flying simulator example
Downloaded function example
TIGA test suite
Demonstrates many of TIGA's functions
Board mode query/initialization program
Demonstrates fixed-point math operations
TIGA-compatible MS-Windows driver (SPK only)
Each subdirectory contains a readme .1st file, complete source, and a
make file to rebuild that particular demonstration. Consult the readme. 1 st
file for a description of the demonstration and rebuilding instructions.
If you opted not to load the TIGA examples during the initial TIGA kit installation, you can install the examples and demonstrations at any time, following
the installation instructions outlined on page 2-4. Simply insert program
disk #1 into drive A: instead of the DDK or SPK disk #1 as directed in step
1. Continue installation as described.
2.2.4
Running a TIGA Demonstration
After installing TIGA on your system, you can run any of the supplied demonstration programs. One such program, tigademo, is a free-running demonstration of TIGA's graphics primitives. The following instructions outline
how to run tigademo:
1) At the MS-DOS prompt, enter
set path=c:\tiga ~
This provides access to TIGA's DOS commands from any directory.
2) Enter
sat UGA=-mc: \tiga ~
This informs TIGA to look in the c: \ tiga directory for TIGA-specific
runtime files.
2-6
Getting Started
Installing TlGA on your System
3)
Enter
cd \tigapgms\tigademo ~
This directory contains the tigademo program.
4)
Enter
tigacd ~
This loads the TIGA communication driver (CD). The CD provides the
communication interface between a TIGA application and the target
TMS340-based board. Once loaded, the CD remains resident in
memory and requires reloading only after rebooting your system.
5) Finally, enter
tigademo ~
This executes tigademo.
You can run any of the other supplied exarnples in a similar manner.
Note:
Because the OOKlSPK is shipped with a TI software development board
(SOB) version of TIGA, you must have an SOB in your system (or have a
version of TIGA compatible with your TMS340-board) before running any
of the supplied examples.
2-7
Installing TlGA on your System
"'=
2.2.5
TIGA Include Files
The directory\tiga \include contains include files used inthe TIGAsource
code itself and when writing TIGA applications. These include files are divided in two groups: those designed to run on the host processor and those
designed to run on the TMS340 processor. They are also divided, as to
whether they are used in C-source files or in assembler source files as follows:
o
Host-side include files
•
C-source
extend.h
tiga.h
typedefs.h
•
Use when calling TIGA extended primitives
Include always in a TIGA C program
Include when using TIGA structure types
Assembler source
extend. inc
Use when calling TIGA extended primitives.
tiga. inc
Include always in a TIGA assembly program.
typedefs. inc Include when using TIGA structure types
o
TMS340-side include files
•
C-source
gspextnd.h
gspglobs.h
gspregs.h
gsptiga.h
gsptypes.h
•
Use for external declarations of all TIGA extended
primitives
Use for external declarations of all TIGA global
variables
Use for TMS340 register definitions
Use for external declarations of all TIGA core
primitives
Include when using TIGA structure types
Assembler source
gspextnd. inc Use for external declarations of all TIGA extended
primitives
gspglobs. inc Use for external declarations of all TIGA global
variables
gspregs. inc Use for TMS340 register definitions
gsptiga. inc Use for external declarations of all TIGA core
primitives
gsptypes. inc Include when using TIGA structure types
gspmac . lib
Use for macro library
2-8
Getting Started
Modifying Autoexec and the Environment
2.3
Modifying Autoexec and the Environment
After installing yourTIGA kit, you maywantto make a few modifications and/
or additions to your autoexec. bat or comparable batch file. Note that these
instructions use C: to identify the hard disk drive. Replace C: with the drive
designator where you installed your particular TIGA kit:
1) Append c: \tiga to the MS-DOS path:
PATH=< existing PATH>;c:\tiga
2)
If you plan to develop TIGA-compatible applications in C or to rebuild
any of the TIGA demos or the TIGA test suite, append
c: \ tiga \ incl ude to the Microsoft C compiler environment variable
INCLUDE:
set INCLUDE=;c:\tiga\include
If you do not currently have an INCLUDE environment variable in your
autoexec . bat file, this command adds it.
3)
If you have the TMS340 C Compiler and assembly-language tools installed on your system, then append c: \tiga \include to the A_DIR
and C_DIR environment variables:
set A DIR=;c:\tiga\include
set C=DIR=;c:\tiga\include
Again, if these environment variables currently do not exist, these commands add them.
4) Add the following TIGA environment variable:
set TIGA= -mc:\tiga
See Section 2.5 on page 2-11 for a complete description of the TIGA
environment variable.
5)
After modifying your autoexec. bat file, run it or reboot your PC.
2-9
Running the T1GA Driver
2.4
Running the TIGA Driver
To load TIG~:
Enter tigacd~ at the MS-DOS prompt. The command syntax for tigacd
is:
tigacd [flag]
Available options:
Flag
Description
-i
Reinstalls the TSR. This option forces a new copy of the TIGA communication driver (CD) to be loaded in memory, thereby superseding
any previously installed CD. Note that reinstalling the TSR with the -i
option forces reloading of the TIGA graphics manager.
-u
Uninstalls the TSR.This option causes the previously installed TIGA
CD to 'be released from memory, disabling TIGA. To re-enable TIGA,
enter: tigacd~ once again.
-5
Informs the TIGA CD to select operating modes valid for the SONY
Multiscan monitor, rather than for the default monitor, the NEC Multisync monitor (SOB version only).
After the TIGA CD is loaded, TIGA is ready to use; however, the TMS340
side of TIGA has not yet been initialized. This is accomplished in one of the
following ways:
a
An application making a call to seCvideomode(TIGA,INIT} checks
whether the TIGA graphics manager (GM) is loaded and running on the
TMS340 side. If so, both the host and TMS340 sides of TIGA are ready.
If not, the GM is loaded, executed, and initialized prior to returning from
the seCvideomode function.
a
Enter tigalnk -lx from the MS-DOS command line after loading the
TIGA CD, to force the TIGA GM to be loaded and executed.
After loading the host and TMS340 sides of TIGA, your application is free
to call TIGA's core primitives.
2-10
Getting Started
The T1GA Environment Variable
2.5
The TIGA Environment Variable
TIGA uses the environment variable TIGA to get information about the location of TIGA system files, dynamic load modules, and the desired interrupt
level. Set the TIGA environment variable using the following syntax:
set TIGA = [flag] [string] [flag] [string]
Currently, TIGA recognizes three flags:
Flag
Description
-m
Specifies the path for TIGA system files
-1
Specifies the path for TlGA dynamic load user modules
-i
Specifies the host interrupt level used by the TIGA communication
driver
When TIGA is initially installed, all TIGA system files are placed in the TIGA
directory of the destination drive. Specify this path using the -m flag of the
TIGA environment variable.
Any dynamic load modules loaded from a TIGA application must be located
in either:
Q
the current directory from which the TIGA application is called or
Q
the path specified by the -1 flag in the TIGA environment variable.
By default, TIGA's communication driver uses interrupt level Ox7F to communicate with an application. Use the -i flag followed by the interrupt level
(in hex format) in the TIGA environment variable to specify an alternate interrupt level.
As an example, assume all TIGA system files are located in c: \tiga, user
dynamic load modules are in d: \d1m, and the desired interrupt level to use
is Ox78. Set the corresponding TIGA environment variable:
set TIGA=-mc:\tiga -ld:\dlm -iOx78 ~
2-11
T1GA Utility Programs
2.6
TIGA Utility Programs
The following TIGA utility programs are in TIGA's root directory \tiga to
simplify porting and/or applications development:
TIGA Utility
cc. exe
cltiga. bat
mg2tiga. exe
tigamode . exe
2.6.1
Description
TMS340 tool shell program, used in make files
that rebuild TIGA's graphics manager
Batch file to compile and link a TIGA application
Utility to convert TMS340 math/graphics fonts to
TIGA compatible fonts
Utility to query available modes and select default
mode
cc Utility
This utility is used primarily by the TIGA graphics manager make files during
rebuilding. It is also useful in compiling TMS340 C or assembling assemblylanguage code.
cc is executed from the MS-DOS command line. Enter cc with no parameters to display usage instructions. Additional information on how to use the
cc utility can be found in the TMS34010 Software Developer's Kit (SDK)
User's Guide.
2.6.2
cl.t:iga Batch File
The cltiga.bat batch file provides an easy way to compile and link a
TIGA-compatible application (contained in a single C source file) to the
TIGA application interface. It also supports symbolic debugging through Microsoft's CodeView ® debugger. The syntax for cltiga is:
cltiga [-dj filename
where -d is an option that specifies symbolic debug processing and filename is the name of the C file to be processed. No extension should be specified on the filename.
Note:
The TIGA application interface library is independent of the Microsoft C
model, thus, the cltiga batch file does not specify any particular model and
uses the default (small) model unless overridden. This can be done by setting the cl environment variable (consult the Microsoft C reference manual
for details).
2-12
Getting Started
TIGA Utility Programs
2.6.3
mq2t.iqa Utility
The mg2tiga utility converts fonts compatible with the TMS340 Mathl
Graphics function library to a format compatible with the TIGA text functions.
The command line syntax for mg2tiga . exe is
mg2tiga
MG font
TIGA font
[ "facename"]
where:
MG font
is a binary or COFF object image of a MathlGraphics compatible font.
TIGA font
is the filename under which the converted font is saved.
facename
is an optional name of the font (up to 31 characters long) enclosed within double-quotes. If this parameter is not specified
on the command line, mg2tiga prompts you for it.
Here is an example of converting the TI Roman 18-point font from the mathl
graphics font library to TIGA format.
1) Locate the library that containsTI Roman fonts. As supplied, this library
is called ti roman • lib and contains 12 fonts. A table of contents of
this library:
gspar -t ti_roman ~
GSP Archiver
Version 3.00
(c) Copyright 1985, 1988, Texas Instruments Incorporated
FILE NAME
ti_romll.obj
ti_rom14.obj
ti_rom16.obj
ti_rom18.obj
ti_rom20.obj
ti_rom22.obj
ti_rom26.obj
ti_rom30.obj
ti_rom33.obj
ti_rom38.obj
ti_rom52.obj
ti_rom78.obj
SIZE
2358
2744
3130
3258
3898
4538
5432
6330
7098
9658
16698
34878
DATE
Thu
Thu
Thu
Thu
Thu
Thu
Thu
Thu
Thu
Thu
Thu
Wed
Jun
Jun
Jun
Jun
Jun
Jun
Jun
Jun
Jun
Jun
Jun
Jun
12
12
12
12
12
12
12
12
12
12
12
18
12:00:32
12:02:20
12:04:12
12:06:06
12:08:06
12:10:16
12:12:34
12:15:00
12:17:36
12:20:42
12:25:00
02:45:56
1986
1986
1986
1986
1986
1986
1986
1986
1986
1986
1986
1986
2) Extract the desired font, in this case ti_rom18. obj.
Example: gspar x ti_roman ti_rom18.obj
8
3) Now use mg2tiga to convert it to TIGA format.
Example: mg2tiga ti_ rom18 . obj roman18. fnt
8
2-13
TIGA Utility Programs
At this point, mg2tiga prompts you to enter a face name for the font.
This facename can be up to 31 characters long and should be the name
of the font.
Example:
MGFL to TIGA font converter
[ Converting: ti rom1S.obj -> roman1S.fnt 1
Enter facename (31 chars max): TI ROMAN ~
After you have entered the face name, mg2t iga displays the MG font header
and then the new TIGA font header. A prompt to press ~ follows each of
these displays. After entering this information, the conversion is complete.
2-14
Getting Started
TlGA Utility Programs
[ -------- Old Font Header -------- ]
fonttype: 9000
firstchar: 0000
lastchar: OOff
widemax: 0010
kernmax: 0000
ndescent: fffd
charhigh: 0011
owtloc: 046a
ascent: OOOe
descent: 0003
leading: 0002
rowwords: 0033
[ Press return ]->
[ -------- New Font Header -------- ]
magic: 8040
length: OOOOOb
facename: TI ROMAN
first: 0000
last: OOff
maxwide: 0010
maxkern: 0000
charwide: 0000
avgwide: 0008
charhigh: 0011
ascent: OOOe
descent: 0003
leading: 0002
rowpitch: 00000330
oPatnTbl: 00000250
oLocTbl: 00003880
oOwTbl: 000048aO
[ Press return ]->
2-15
TlGA Utility Programs
2.6.4
tigamode Utility
The tigamode utility allows you to interrogate the operating modes of the
TIGA-compatible graphics board in your system. It also enables you to select a default mode for your board. For additional information and complete
source for the tigamode utility, consult the \tigapgms\ tigamode directory.
2-16
Getting Started
Non-TlGA Development Utility Programs
~'l';~~'::_·
2.7
_ _;:;;;X~~»';:;W..x~~::-7":;::-;~~X~%,;:~~::;:;~~.;:;s::.~::SS~:I:'.:'.:;~.xS:::I:!~~:;::o~:-v.&..m~:-,:>:;;;:;:~;~::y/.m;:vH..:;:;:;:7~M:::::;::%9;;;X::Y/.:.::.:w/;.~..:o:~».>~;:;
Non-TIGA Development Utility Programs
TIGA development and/or porting relies heavily on the use of the Microsoft's
Macro Assembler and/or Microsoft's C compiler packages. Specifically,
both packages must be version 5.0 or later to ensure compatibility with
TIGA.
TIGA contains batch files that aid in rebuilding the TIGA communications
driver and graphics manager (if you have the SPK), and batch files to compile and link your applications with the TIGA applications interface. These
batch files use the following utility programs, which are bundled with the indicated Microsoft programming package:
Utility program
Description
cl . exe
lib. exe
link. exe
make. exe
Microsoft C compiler shell program
MS-DOS library manager, supplied with DOS
MS-DOS linker, supplied with both packages
Make utility, supplied with both packages
These programs must be accessible from TIGA's batch files (via the PATH
environment variable) to ensure proper operation.
2-17
TlGA Syntax and Programming Examples
2.8
TIGA Syntax and Programming Examples
The definition of the TIGA syntax and the coding examples supplied in this
guide are written primarily in Microsoft C, since Microsoft C is commonly
used to write DOS applications. The high-level language syntax in C is similar to that of many other high-level languages and even programmers unfamiliar with C will understand the syntax. TIGA, however is not restricted to
Microsoft C, although this initial release does rely on the Microsoft C calling
conventions. Future versions of TIGA may be developed for other C compilers and other languages.
The current version of TIGA also provides a simple interface for Microsoft
assembly language programmers. The three TIGA include files (tiga. h,
extend. h, and typedefs. h) all have assembly language equivalents that
use macros to provide a simple interface to call TIGA functions. An example
of how to call TIGA functions from the assembler is provided in the
\tigapgms\asmtst directory. Consult the readme .1st file in that directory
for more details on the use of macros. Also provided in the include files are
macros used to simplify the definition of user extensions. These macros,
which mirror their C counterparts, are described in Chapter 4 of this user's
guide.
2-18
Getting Started
Chapter 3
TIGA Application Interface
!lSi i
lim!!
!
Hi
: ::
Si
i:
i
The following sections list the TIGA primitives, first in their functional
groups, and then alphabetically, with a description and example of their use.
Appendix B provides further information concerning the drawing functions.
This chapter describes the TIGA application interface, including the following topics:
Section
3.1
3.2
3.3
Page
Base Set of TIGA Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 3-2
Summary Table of Functions by Functional Group ........... 3-3
Alphabetical List of Functions ............................ 3-13
3-1
i
Base Set of T1GA Primitives
3.1
Base Set of TIGA Primitives
From an application programmer's point of view, TIGA (Texas Instruments
Graphics Architecture) consists of a set of functions which the application
can invoke to perform graphics-related operations. These functions may run
entirely on the host PC, on the TMS340 board, or on both. They fall into two
classes, core and extended:
I:l
Core Primitives
The core primitives, such as set-palet, are always available during a
TIGA session.
I:l
Extended Primitives
The extended primitives, such as filLrect, consist primarily of drawing
functions. They are extended because the application has to load them
when initializing TIGA. If the application requires installation of its own
drawing functions, with parameters different from those used in TIGA,
the extended primitives can be excluded at initialization time. Excluding
the extended primitives frees up memory on the TMS340 board for user
extensions.
3-2
T1GA Application Interface
--
Summary Table of Functions by Functional Group
3.2
3.2.1
Summary Table of Functions by Functional Group
Graphics System Initialization Functions
Function
cd_is_alive
function_implemented
gecconfig
geCmodeinfo
geCvideomode
gsp_execute
installJ)rimitives
install_usererror
loadcoff
set_config
seCtimeout
seCvideomode
synchronize
Description
Return if TIGACD is running
Return if a function is implemented
Return board configuration
Return board configuration
Return current emulation mode
Execute a COFF program
Install extended primitives
Install user error handler
Load a COFF program
Set graphics configuration
Set timeout timing value
Set emulation mode
Make host wait for GSP to idle
Type
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
The graphics system initialization functions deal with the initialization of the
TIGA environment. Every application must call seCvideomodewith a TIGA
argument prior to invoking any other TIGA function. There are different
styles of initialization that can be performed and they are detailed in the description of seCvideomode. Similarly, on exit, every TIGA function must
call seCvideomode with a mode of PREVIOUS or some other IBM emulation
mode. If the TMS340 board also serves as the primary graphics adapter,
seCvideomode switches the TMS340 board back into emulation mode
prior to returning to DOS.
To use the TIGA extended primitives, the application must first call the
install_primitives function. This call needs to be done only once, if the dynamic heap pool on the TMS340 board has not been reinitialized.
The geCconfig function returns the current board configuration (resolution,
pixel size etc) to the application. Typically a board can be configured in more
than one mode and the geCmodeinfo, set_config functions are provided
to inquire and select alternate modes. Typically an application uses whatever mode the board is set up in (via geCconfig). The end user can swap between different modes with the TIGAMODE utility (described in Chapter 2).
That utility makes calls to the geCmodeinfo and seCconfig functions.
TIGA consists of two distinct parts: a host part (the communication driver),
which takes data from the application and sends it to one of the communication buffers accessible to the TMS340, and a TMS340 part (the graphics
manager), which takes the data from the host and performs the graphics op3-3
Summary Table of Functions by Functional Group
eration. The processors in these two portions work asynchronously. Sometimes the host portion has to waitfor the TMS340 portion; for example: when
the TMS340 returns data to the host or when the host waits for a free communication buffer to use. The time the host has to wait for the TMS340 depends on what the TMS340 is doing for the application.
TIGA has a built-in default time of 5 seconds, after which it displays an error
message on the screen to inform the application thatthere was no communication with the TMS340. This allows the user to break out if there is an error,
or to continue waiting. If this default time is not acceptable it can be changed
using the seCtimeout function. The application can trap error calls by installing its own error handler function using instalLusererror . There is an
example of this after the description of InstalLusererror.
Sometimes it is desirable to force the host to wait for the TMS340 to complete an operation before proceeding. Consider the case where the
TMS340 is performing a bitblt of data into memory and the host is then to
upload the data using gsp2hostxy. Because the host and TMS340 work
asynchronously, it is possible for the gsp2hostxy function to start copying
data before the bitblt has completed. This can be solved by the application
calling the synchronize function, which causes the host to wait until all
TMS340 functians are completed, prior to the call to upload the data.
3.2.2
Clear Functions
Function
clear_frame_buffer
clear_page
clear_screen
Description
Clear entire frame buffer
Clear current drawing page
Clear screen
Type
Core
Core
Core
The clear functions provide different ways to clear the screen. They all attempt to utilize any special memory functions (such as shift-register transfers) that the board or the memory chips themselves may have to perform
the clear function as quickly as possible. The clear_frame_buffer clears
the entire frame buffer, which may consist of multiple display pages and
areas of offscreen (non-displayable) memory.
The clear_screen function clears only the visible portion of the screen. For
configurations that contain multiple display pages, only the current drawing
page is cleared. The clearJ)age function is similar to the clear_screen
function except that it does not ensure that data in offscreen memory is kept
intact. This is because, depending on how the frame buffer is designed, it
may be possible to clear a page using shift-register transfers; however, certain offscreen memory areas may also be affected. Thus, to keep offscreen
memory integrity, an application should use the clear_screen function. If
3-4
TIGA Application Interface
Summary Table of Functions by Functional Group
offscreen memory integrity is not a concern, the clearj)age function may
be the fastest option on certain boards.
3.2.3
Graphics Attribute Control Functions
Function
Type
Description
Core
cpw
Compare point to window
Core
Return foreground/background colors
geCcolors
Core
Return current environment structure
geCenv
Core
getJ)mask
Return color plane mask
getJ)pop
Return pixel processing operation
Core
Core
Return transparency mode
geCtransp
geCwindowing
Return windowing mode
Core
Set background color
Core
seCbcolor
set_clip_rect
Set clipping rectangle
Core
Core
Set foreground and background colors
seCcolors
Ext
seCdraw_origin
Set drawing origin
Core
seCfcolor
Set foreground color
Ext
setJ)atn
Set current pattern description
Ext
setJ)ensize
Set current pensize
Core
setJ)mask
Set color plane mask
setJ)pop
Core
Set pixel processing operation
Core
Set transparency mode
seCtransp
Core
secwindowing
Set windowing mode
Core
transp_off
Disable pixel transparency
transp_on
Core
Enable pixel transparency
The graphics outputfunctions use implied operations called the graphics attributes to perform the drawing operations described below. These attributes are initialized and can be queried using the functions in this group. The
graphics attributes consist of
Foreground Color Primary drawing color of all primitives. The color value is an index running from 0 to two-to-the-power-of-the-current-pixel-size. The value will typically
be an index into the current palette (see next section).
Background Color Secondary drawing color, used in patterns, text and
bitblt functions.
Plane Mask
Enables the bits in a pixel to represent different
planes.
Pixel Processing
Determines the operation performed on source and
destination pixels in any pixel operation.
Transparency
Determines whether a pixel write should be inhibited
if the pixel color is transparent.
3-5
Summary Table of Functions by Functional Group
Windowing
Allows regions of the screen to be clipped to ensure
no drawing occurs outside the designated window.
Drawing Origin
By default the drawing origin is the top-left hand corner of the screen, but this can be moved anywhere.
Fill Pattern
Used by all the patn drawing functions that fill a region with a pattern instead of a solid color.
Drawing Pen
Used by all the pen drawing functions to outline a region with a pen of the specified width and height, rather than with a single- pixel wide line.
For further details concerning the drawing functions, see Appendix B.
3.2.4
Palette Functions
Function
geCnearesCcolor
geCpalet
getJ>alet_entry
iniCpalet
seCpalet
setJ>aleCentry
Description
Return nearest color in a palette
Return an entire palette
Return a palette entry
Initialize default palette
Set an entire palette
Set a palette entry
Type
Core
Core
Core
Core
Core
Core
The palette functions are graphics attributes and deserve special attention
because they may vary from board to board. Ideally, the application should
be able to set the palette to any particular desired value, but if the palette
is in ROM, this is not possible. Use function_implemented to determine
if the palette entries can be set. If they cannot be set, use the geCnearesCcolor function to find the best entry to the desired color stored in ROM.
Also, different palettes allow different bits-per-gun. Determine the bits-pergun using the palet_gun_depth field in the CON FIG structure or the
get-palet function. The getJ>alet and get-paleCentry functions return
the physical colors .stored in the palette. Thus, if a palette entry is set with
8 bits of red to hexadecimal FF on a particular board (such as the TI SOB),
where only 4 bits per gun are used, invoking geCpaleCentry for that entry
would return a red value of FO to indicate that the LS 4 bits were ignored.
An example describing this is shown after the description of
get-palet_entry.
If possible, the palette is initialized to a default set of commonly-used colors
(defined in the TIGA.H insert file) by a call to init.."pa1et.
3-6
TIGA Application Interface
Summary Table of Functions by Functional Group
3.2.5 Graphics Output Functions
Function
draw_line
draw_oval
draw_ovalarc
drawJ>iearc
drawJ>oint
draw_polyline
draw_rect
filLconvex
fill_oval
fillJ>iearc
fillJ>olygon
filUect
frame_oval
frame_rect
patnfilLconvex
patnfill_oval
patnfilU>iearc
patnfill-polygon
patnfilUect
patnframe_oval
patnframe_rect
patnpen_line
patnpen_ovalarc
patnpen-piearc
patnpen-point
patnpen-polyline
pen_line
pen_ovalarc
pen-piearc
pen-point
pen-polyline
seed_fill
seed_patnfill
styled_line
Description
Draw line
Draw ellipse outline
Draw ellipse arc
Draw ellipse pie slice
Draw single pixel
Draw list of lines
Draw rectangle outline
Draw solid convex polygon
Draw solid ellipse
Draw solid ellipse pie slice
Draw solid polygon
Draw solid rectangle
Draw oval border
Draw rectangular border
Draw patterned convex polygon
Draw patterned ellipse
Draw patterned pie slice
Draw patterned polygon
Draw patterned rectangle
Draw patterned oval border
Draw patterned rectangular border
Draw line with pattern and pen
Draw oval arc with pattern and pen
Draw pie slice with pattern and pen
Draw pixel with pattern and pen
Draw lines with pattern and pen
Draw line with pen
Draw an oval arc with pen
Draw pie slice with pen
Draw point with pen
Draw lines with pen
Fill region with color
Fill region with pattern
Draw styled line
Type
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
Ext
The graphics output functions are self-explanatory. Specific examples on
how to use fill patterns are shown in patnfllLplearc and for drawing pens
in patnpen_line. These examples also explain other patn and pen functions. Additional examples of drawing functions are given for draw_line,
draw_oval, draw_ovalarc, draw-point, draw-polyline, fill_polygon,
and styled_line.
For further details concerning the drawing functions, see Appendix B.
3-7
Summary Table of Functions by Functional Group
3.2.6
Poly Drawing Functions
Function
Description
Type
drawJ)olyline
Draw polyline
Ext
fill_convex
Ext
Fill convex polygon
Ext
fillJ)olygon
Fill polygon
Ext
Pattern fill convex polygon
patnfilLconvex
Ext
Pattern fill polygon
patnfillJ)olygon
Pattern pen polyline
Ext
patnpenJ)olyline
Ext
Pen polyline
penJ)olyline
The TIGA communication driver functions pass the arguments of all the
TIGA primitives into acommunication bufferforthe TIGAgraphics manager
to use. Nearly all TIGA primitives have fixed size arguments that fit easily
into the communication buffer. This is not the case with the poly drawing
functions, which have a point list parameter that can be of any length. It is
easy for the function to overflow the buffer, destroying the TIGA environment. The application can either check the size of the data that it is sending,
againstthe communication buffer size in the CON FIG structure, or it can use
alternate entry points (with an _8 appended to the function name), that use
a buffer, allocated from the dynamic heap pool, to store the data. However,
these alternate entry points are slower.
3.2.7
Workspace Functions
Function
Description
Type
fill_polygon
Fill polygon
Ext
Return offscreen workspace
Core
geCwksp
patnfillJ)olygon
Pattern fill polygon
Ext
Set
a
temporary
workspace
Core
seCwksp
The polygon fill functions use an implied operand of a temporary workspace.
This workspace is a 1 bit-per-pixel representation of the display screen and
may be allocated from offscreen-memory in the TIGA port for the board being used. This can be determined by the gecwksp function. If the area cannot be allocated from offscreen-memory, then it must be allocated from heap
and assigned using the secwksp function. An example showing how to do
this follows the flllJ)olygon description.
3.2.8
3-8
Pixel Array Functions
Function
Description
bitblt
seCdstbm
seCsrcbm
swap_bm
zoom_rect
Bitblt source array to destination
Set destination bitmap
Set source bitmap
Swap source and destination bitmaps
Zoom source rectangle
Type
Ext
Ext
Ext
Ext
Ext
TIGA Application Interface
Summary Table of Functions by Functional Group
The bitblt function transfers a rectangular array of pixels in TMS340
memory. The function uses two implied operands (source bitmap and destination bitmap) which are set, by default, to the screen. When they are set
to a linear address, the bitblt function can then save data offscreen and restore it again (see example following seCdstbm). The bitblt function can
also be used to expand a linear bitmap which is at 1 bit-per-pixel to a color
bitmap (see example following zoom_rect).
The destination bitmap is an implied operand for all drawing functions. If it
is set to anything other than the screen, all drawing primitives (other than
bitblt) abort. In the future, linear drawing capability may be added to each
of the drawing functions so they can draw into a linear bitmap.
The source bitmap is ignored by all functions except bitblt and zoomJect.
The latter is used to scale a source pixel array into any size destination array.
See the example following the function description.
3.2.9
Text Functions
Function
delete_font
get_fontinfo
geCtextattr
iniCtext
instalUont
selecCfont
set_textattr
text_out
text_width
Description
Remove a font from the font table
Return font physical information
Return text rendering attributes
Initialize text drawing environment
Install font into font table
Select an installed font for use
Set text rendering attributes
Render an ASCII string
Return the width of an ASCII string
Type
Ext
Core
Ext
Core
Ext
Ext
Ext
Core
Ext
The text functions are partly core and partly extended primitives. In the core
is a system font and the texcout primitive along with geCfontinfo (which
returns font size information) and iniCtext (to reset the text environment).
The extended primitives instalLfont, selecCfont, and delete_font allow
the addition of TIGA fonts. There are over 100 TIGA fonts available, which
the application loads from disk on the host side (or links-in with the host
application) and downloads onto the TMS340 side. An example illustrating
this is in instalLfont. The setlgeCtextattr function allows the text attributes such as inter-character spacing, to be adjusted by the application.
For more details on the font structure, see Appendix A.
3-9
Summary Table of Functions by Functional Group
3.2.10 Cursor Functions
Function
geccurs_state
get_curs_xy
set_curs_shape
seccurs_state
set_curs_xy
Description
Return cursor current state
Return cursor position
Set cursor shape
Make cursor visible/invisible
Set current cursor position
Type
Core
Core
Core
Core
Core
The cursor functions support the graphics cursor routine. The cursor can be
enabled or disabled via the set_curs_state function and its position can be
modified using seCcurs_xy. The seCcurs_shape enables an arbitrary
shaped cursor to be used. An example showing how the cursor may be driven by the host mouse follows the description of seCcurs_shape.
3.2.11 Graphics Utility Functions
Function
getJ)ixel
Imo
page_busy
page_flip
peek_breg
poke_breg
rmo
waiCscan
Description
Read contents of a pixel
Return left-most-one bit number
Return status of page flipping
Set display and drawing pages
Read from a 8-file register
Write to a 8-file register
Return right-most-one bit number
Wait for a designated scan-line
Type
Ext
Core
Core
Core
Core
Core
Core
Core
The graphics utility functions are a group of miscellaneous graphics-related
functions, most of which require no explanation other than what is given with
the individual functions.
The waiCscan and page_flip/busy functions are mechanisms to aid animated sequences. waiCscan waits for a particular scan line, enabling data
to be drawn on one part of the screen while a different part is being displayed. This feature provides a flicker-free display but is limited in the
amount that it can draw before the display moves to the area that is being
drawn into. The use of multiple drawing pages is a much more effective way
where one page can be drawn while another is being displayed. This is the
only way to ensure a flicker-free display. However, it does require at least
double the amount of memory for the frame buffer.
The CON FIG structure supplies the number of display pages. If the number
of pages is greater than 1, use the page_flip function to select a page for
drawing and a page for displaying. The flip of the pages is synchronized with
the start of V8LNK for the best visual effect. The page_busy function must
be polled prior to drawing into the new page.
3-10
TIGA Application Interface
Summary Table of Functions by Functional Group
3.2.12 Pointer-Based Memory Management Functions
Function
geCoffscreen_memory
gsp2gsp
gsp_calloc
gsp_free
gsp_malloc
gsp_maxheap
gsp_minit
gsp_realloc
Description
Return offscreen memory blocks
Copy from GSP memory to GSP memory
Allocate and clear GSP memory
Deallocate GSP memory
Allocate GSP memory
Return largest free block
Reinitialize GSP memory heap pool
Resize allocated block of memory
Type
Core
Core
Core
Core
Core
Core
Core
Core
The heap management functions (gsp_malloc, gsp_free, gsp_calloc,
gsp_realloc) are familiar to C application programmers. Identical heap
management for host memory is provided in Microsoft C runtime support.
The gsp_minit function initializes the heap pool (freeing all allocated pointers). Because the program memory is shared between stack and heap, this
function can also be used to adjust the memory used for stack (and thus,
leaving the remainder memory for heap). The gsp_maxheap function returns the largest contiguous block of heap available (which is also the total
heap size at the start of an application) and can determine how much data
can be loaded from the host to the TMS340.
The gsp2gsp function provides a memory copy function (as opposed to
bitblt, which is a pixel array copy). It handles overlapping memory areas.
The geCoftscreen_memoryfunction returns data concerning the size and
addresses of available offscreen memory, which are separate from the heap
pool. Allocation of these areas is performed by the application. The offscreen memory may be used for the temporary workspace (see Section
3.2.7).
3.2.13 Communication Functions
Function
cop2gsp
field_extract
field_insert
geCvector
gsp2cop
gsp2host
gsp2hostxy
host2gsp
host2gspxy
seCvector
Description
Copy coprocessor to GSP memory
Extract data from GSP memory
Insert data into GSP memory
Get address at a TMS340 trap vector
Copy GSP memory to coprocessor
Copy from GSP into host memory
Copy rectangular area from GSP to host
Copy from host into GSP memory
Copy rectangular area from host to GSP
Set contents of GSP trap vector
Type
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
3-11
Summary Table of Functions by Functional Group
The communication functions transfer data between host and TMS340
memory spaces, or between TMS340 and its coprocessor.
3.2.14 Extensibility Functions
Function
create_aim
create_esym
flush_esym
flush_extended
geUsrJ)riorities
install_aim
installJ)rimitives
install_rim
seUnterrupt
Description
Create absolute load module
Create external symbol table file
Flush external symbol table file
Flush all user extensions
Return interrupt service routine priorities
Install absolute load module
Install extended drawing primitives
Install relocatable load module
Set an interrupt handler
Type
Core
Core
Core
Core
Core
Core
Core
Core
Core
The extensibility functions are all concerned with extensibility. Their use is
described in detail in Chapter 4.
3-12
TIGA Application Interface
Alphabetical List of Functions
3.3
Alphabetical List of Functions
This section contains a reference for TIGA functions in alphabetical order.
Each discussion
Q Shows the syntax of the function declaration and the arguments that the
function uses.
Q
Contains a des'cription of the function operation, which explains input
arguments and return values.
Q Provides an example of the use of some functions.
3-13
bitblt
BitBlt in GSP Memory
Syntax
void bitblt(width, height, srcx, srcy, dstx, dsty)
short width;
short height;
short srcx;
short srcy;
short dstx;
short dsty;
Type
Extended
Description The bltblt function copies data from the TMS340's source bitmap, which is
installed by the seCsrcbm function into the destination bitmap. The destination bitmap is in turn installed by the set_dstbm function. The bitmap data
is a rectangular area whose top left-hand corner is at coordinates
(srcx, srcy) in the source bitmap of size width by height, into the destination bitmap, starting at coordinates (dstx,dsty). The pixel size of the two
bitmaps should either be equal or, if they are not, one of the pixels sizes must
be equal to 1.
Ifthe pixel sizes are equal, then the rectangular area is copied. If both source
and destination bitmaps are set to the screen, then a check is made to see
if the areas overlap. If they do, the bitblt direction is set to avoid destroying
the source bitmap before it is copied.
If the source bitmap pixel size is 1, the bitmap is expanded to color in the
destination array. 1s in the source bitmap are drawn in the current foreground color and Os are drawn in the current background color.
If the destination bitmap pixel size is equal to 1, then a contract function is
performed. Pixels in the source array that are equal to the current background color are set to 0 in the destination array. All other colors are set to
1.
When the destination bitmap is set to the screen, the function attempts to
clip the destination bitmap to the current clipping rectangle set by the
seCclip_rect function. This only occurs if the pitch of the source and destination pitch are a power of two (greater than or equal to 16). The source
pitch is set by the user in the seCsrcbm function. If the destination bitmap
is the screen, its pitch is defined in the dispyitch field of the CONFIG
structure (see Appendix A). If the pitches are not a power of two, you must
pre-clip the destination bitmap.
3-14
TfGA Application Interface
BitBlt in GSP Memory bitblt
Example
#include
#include
#include
CONFIG config;
main()
{
if (set_videomode(TIGA, INIT I CLR_SCREEN))
if (install-primitives() >= 0)
{
get_config(&config);
set_fcolor(BLUE);
/* fill the top left quarter of the screen
/* with a blue rectangle
fill_rect(config.mode.disp_hres»l,
config.mode.disp_vres»l, 0, 0);
/* copy one quarter of the rectangle with top
/* left-hand corner at the center of the screen
bitblt (config.mode.disp_hres»2,
config.mode.disp_vres»2, 0, 0,
config.mode.disp_hres»l,
config.mode.disp_vres»l);
*/
*/
*/
*/
set_videomode(PREVIOUS, INIT);
3-15
cd_is_alive Return if TlGACD is Running
Syntax
int cd_is_alive ()
Type
Core
Description The cd_is_allve returns true (nonzero) if the communication driver (CD)
has been installed, or false (zero), otherwise. This function is an alternate
entry point to seCvideomode for applications that require only the hostside entry points of TIGA without loading the graphics manager. If this
function returns true (nonzero), then the following host-only primitives may
be used:
0
0
0
0
0
0
0
0
field_extract
field_insert
gsp2host
gsp2hostxy
gsp_execute
host2gsp
host2gspxy
loadcoff
Before a call to any other TIGA function, a call must first be made to
seCvideomode with a TIGA parameter.
3-16
TIGA Application Interface
Clear Entire Frame Buffer
Syntax
void clear_frame_buffer(color)
long color;
Type
Core
clear frame buffer
Description The clear_frame_buffer function performs a rapid clearing of the entire
display memory, by setting it to the color index specified. If the color is set
to -1 the current background color is used. If the configuration is such that
the screen can be cleared using shift-register transfers, this is done,
providing a very rapid clearing. If the configuration contains multiple display
pages all pages are cleared. The integrity of offscreen data cannot be
guaranteed using this function. If this is of concern to the calling program,
then the clear_screen function should be used.
If the graphics display board uses display memory to store palette information (as in the TMS34070), this area should be left intact by this function.
3-17
clear-page
Clear Current Drawing Page
Syntax
void clearyage (.color)
long color;
Type
Core
Description The clear-page function performs a rapid clearing of the current drawing
page by setting it to the color index specified. If the color is set to -1 the current background color is used. It provides very rapid clearing if the
configuration allows the use of shift-register transfers. If the configuration
contains multiple display pages, only the current drawing page is cleared.
However, the integrity of offscreen data cannot be guaranteed using this
function. If this is of concern to the calling program, then the clear_screen
function should be used.
If the graphics display board uses display memory to store palette information (as in the TMS34070), this area should be left intact by this function.
3-18
TIGA Application Interface
Clear Screen
Syntax
void clear_screen (color)
long color;
Type
Core
clear_screen
Description The clear_screen function performs a rapid clearing of only the visible
portion of the display memory, by setting it to the color specified index. If the
color is set to -1, the current background color is used. It provides very rapid
clearing if the configuration allows the use of shift-register transfers.
However, this function clears only the current drawing page (in a multiple
paged frame buffer) and does not affect any offscreen memory. If the
offscreen memory data does not have to be conserved, then a more rapid
fill may be possible using the clearJ)age function.
If the graphics display board uses display memory to store palette information (as in the TMS34070), this area should be left intact by this function.
Example
See function_implemented.
3-19
Syntax
void cop2gsp(copid, copaddr, gspaddr, length)
short copid;
long copaddr;
long gspaddr;
long length;
Type
Core
Description The cop2gsp function copies data from the address space of the coprocessorwith ID copid (a number from 0-7, with 4 being broadcast, as defined
in the TMS34020 specification) into TMS340 memory. The data to be transferred is in 32-bit long words.
3-20
TIGA Application Interface
Compare Point to Window CpW
Syntax
Type
short cpw(x, y)
short x, Yi
/* pixel coordinates */
Core
Description The cpw function generates 4-bit outcode based on a pixel's position relative to the current clipping window. Arguments x and yare the coordinates
of the pixel.
The outcode value is contained in the 4 LSBs of the return value. Outcode
values include
00002
if the point lies within the window.
01xX2
if the point lies above the window.
10xx2
if the point lies below the window.
xx012
if the point lies left of the window.
xx102
if the point lies right of the window.
Refer to the TMS34010 User's Guide for a detailed description of the outcodes.
3-21
create_aim
Create Absolute Load Module
Syntax
int create_a1m(r1m_name, a1m_name)
char far *r1m_name;
char far *a1m_name;
Type
Core
Description The create_aim function converts the relocatable load module (specified
by r1m_name) into an absolute load module and saves it under the filename
specified by a1m_name. If no file extension is supplied for the RLM, then an
extension of . RLM is used. If no extension is supplied for the ALM, then an
extension of . ALM is used. If no path information is specified, this function
looks first in the current directory and then in the directory specified by the
TIGA environment variable.
If the ALM file already exists, the procedure does nothing. This saves time
by creating the ALM file only once. If a new ALM file is desired, the old one
must be deleted explicitly. For more details on extensibility and an example
of the use of this function refer to Chapter 4.
1fthe fu nction terminates correctly, zero is returned; if an error occurs, a negative error code is returned.This function returns these error codes:
Error
Code
3-22
Description
-1
System Error-Could not find TIGALNK in the main TIGAdirectory,
either the TIGA environment variable -m option is not set or that
directory does not contain TIGALNK. EXE.
-3
Out of Memory - Not enough host memory to run TIGALNK or not
enough TMS340 memory to store the ALM
-4
Communication Driver not Running - Run TIGACD
-5
Graphics Manager not Running - Run TIGALNK
-6
Missing RLM - Either the spelling of the RLM filename does not
match the RLM filename in the current directory or the -1 option of
the TIGA environment variable is not set up.
-7
Symbol File Error-I/O error obtained in accessing the symbol file.
The -m option of the TIGA environment variable is not set or the
directory does not contain TIGA340. sYMorthe file is corrupt. In the
latter case recopy this file from your backup disk.
-10
Symbol Reference - An unresolved symbol was referenced by the
RLM. Determine the name either by producing a link map for the
RLM or by invoking TIGALNK from the command line using the -ec
flag.
-lx
TIGA Application Interface
Create Absolute Load Module
create_aim
===*"«-~~x~.::::::::::::::~-:::m~.:::::::-.::::::s~~y,;::.h~-::-'::::~.;'«>::'~.'X'"~~'~~»»;';*;;;:;:>-»'::"~;:;:;-~':;'O;:;:;:;:;~~:s,.~».:x:;::
Error
Code
-12
Description (continued)
Symbol Table Mismatch - The modules installed in the symbol
table do not match those the TIGA graphics manager has installed.
Reinitialize the modules by a call to flush_extended and install
them again.
3-23
create_esym
••••
Create External Symbol Table File
~;:;~/d~~:l:iW~~~~.::::::::::::::::~~.::::»;m:::::::::::».;m:::::l:i;::~··
Syntax
int create_esym(gm_name)
char far *gm_name;
Type
Core
~M.J:i'~~~'S'.;S:;~;::!::~·y'&..:;n:;
Description The create_esym function does not need to be called by the user. It is pro-
vided as a procedural level interface to the linking loader. It should be used
instead of calling the linking loader directly, to provide compatibility with future versions of TIGA.
This function creates an external symbol table file from the supplied TIGA
graphics manager file. If no file extension is supplied, then a file extension
of . OUT is used. The external symbol table is saved under the name
TIGA340. SYM. After creation, this file will contain only the global (or external)
symbols that were contained in the graphics manager file. During subsequent installation of relocatable load modules, this file is used to resolve external references. Also any external symbols contained in a RLM are added
to this file during the installation process so those symbols can be referenced by other RLMs.
If no pathname information is supplied for the gm_name, this function uses
the path specified by the TIGA environment variable. The external symbol
file created also uses this path information. For more details on extensibility,
the use of this function refer to Chapter 4.
If an error occurs, a negative error code is returned. If this function terminates normally, zero is returned.
This function returns these
Error
Code
3-24
Description
-1
System Error - Could not find TIGALNK in the main TIGA directory,
either the TIGA environment variable -m option is not set or that directory does not contain TIGALNK. EXE.
-4
Communications Driver not Running - Run
-5
Graphics Manager not Running - Run
-7
Symbol File Error - I/O error obtained in accessing symbol file.
The -m option of the TIGA environment variable is not set or the directory does not contain TIGA340. SYM or the file is corrupt. In the
latter case recopy this file from your backup disk.
-11
COFF File not Absolute - The COFF file argu ment for this function
is not linked to an absolute address.
TIGACD.
TIGALNK -lx.
TlGA Application Interface
Create External Symbol Table File create_ esym
Error
Code
-12
Description (continued)
Symbol Table Mismatch - The modules installed in the symbol
table do not match those the TIGA graphics manager has installed.
Reinitialize the modules by a call to flush_extended and install
them again.
3-25
delete_font Delete a Font from Table
Syntax
int delete_font (id)
short idi
Type
Extended
Description The delete_font function removes from the font table the installed font referenced by id. A nonzero value is returned if the font was successfully
removed, and a value of zero if the font was not installed. Note that if the
font removed was also the one selected forcurrent text drawing operations,
the system OEM font is selected.
3-26
TlGA Application Interface
Draw Line
Syntax
Type
void draw_line (xl, yl, x2, y2)
short xl, yl;
/* start coordinates
short x2, y2;
/* end coordinates
draw_line
*/
*/
Extended
Description The draw_line function uses Bresenham's algorithm to draw a line from the
starting point to the ending point. xl and yl specify the starting coordinates;
x2 and y2 specify the ending coordinates. The line is one pixel thick and is
drawn in the current foreground color.
3-27
draw_line Draw Line
Example
#include
#include
#include
CONFIG config;
main ()
{
short xs, ys, xe, ye, i, color;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
xs = config.mode.disp_hres»l;
ys = config.mode.disp_vres»l;
set_fcolor(RED);
/* set up an add pixel processing option to affect */
/* overlapping lines in the center of the screen
*/
set-ppop(16);
/* draw lines at diff. orientations
*/
for (xe = 5, ye = 5; xe <= config.mode.disp_hres-6;
xe += 17)
draw_line(xs, ys, xe, ye);
for (xe = 5, ye = config.mode.disp_vres-6;
xe <= config.mode.disp_hres-6; xe += 17)
draw_line (xs, ys, xe, ye);
for (xe = 5, ye = 10; ye <= config.mode.disp_vres-6;
ye += 17)
draw_line (xs, ys, xe, ye);
for (xe = config.mode.disp_hres-6, ye = 10;
ye <= config.mode.disp_vres-6; ye += 17)
draw_line(xs, ys, xe, ye);
set_videomode(PREVIOUS, INIT);
3-28
TIGA Application Interface
Draw Oval
Syntax
Type
draw_oval
void draw_oval(w, h, xleft, ytop)
short w, h;
/* width, height of recto
short xleft, ytop;
/* coordinates at top left corner
*/
*/
Extended
Description The draw_oval function draws the outline of an ellipse, given the minimum
enclosing rectangle in which the ellipse is inscribed. The ellipse is in standard position, with its major and minor axes parallel to the coordinate axes.
The enclosing rectangle is defined by four arguments:
Cl The width w
Cl The height h
Cl The coordinates of the top left corner (xleft, ytop)
The outline is one pixel thick and is drawn in the current foreground color.
3-29
draw_oval Draw Oval
Example
Unclude
#include
#include
CONFIG config;
main ()
{
int w, h, x, y;
if (set_videomode(TIGA, INIT I CLR_SCREEN))
{
if (install-primitives() >= 0)
{
get_config(&config);
/* restrict drawing to window in center of screen
set_clip_rect(config.mode.disp_hres»l,
config.mode.disp_vres»l,
config.mode.disp_hres»2,
config.mode.disp_vres»2);
set_fcolor(GREEN);
/* draw various sizes ellipses
for (w = 0, x = 4; w < config.mode.disp_hres/20;
++w, x += w + 3)
for (h = 0, y = 4; h < config.mode.disp_vres/20;
++h, y += h + 3)
draw_oval(w, h, x, y);
*/
*/
set_videomode(PREVIOUS, INIT);
3-30
TIGA Application Interface
Draw Oval Arc
Syntax
void draw_ovalarc(w, h,
short w, h;
short xleft, ytop;
short theta;
short arc;
draw_ovalarc
xleft, ytop, theta, arc)
/* width and height
/* top left corner
/* starting angle (degrees)
/* angle extent (degrees)
*/
*/
*/
*/
Type
Extended
Description
The draw_ovalarc function draws an arc taken from an ellipse. The ellipse
is in standard position, with the major and minor axes parallel to the coordinate axes. The arc is one pixel thick and is drawn in the current foreground
color.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
I;l The width w
I;l The height h
I;l The coordinates of the top left corner (xleft, ytop)
The last two arguments define the limits of the arc:
I;l The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
I;l The arc extent, are, specifies the number of degrees (positive or nega-
tive) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
3-31
draw_ovalarc Draw Oval Arc
Example
#include
#include
#include
CONFIG config;
/* x coordinate of screen center */
#define XC
(config.mode.disp_hres»l)
/* y coordinate of screen center */
#define YC
(config.mode.disp_vres»l)
/* x coordinate of screen limit */
#define XMAX (config.mode.disp_hres-4)
/* y coordinate of screen limit */
#define YMAX (config.mode.disp_vres-4)
/* x increment */
#define OX (config.mode.disp_hres/40)
/* y increment */
#define OY
(config.mode.disp_vres/40)
#define MAXBYTES 2048
main()
{
short w, h;
PTR
addr;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
/* draw a spiral */
set_fcolor(YELLOW);
for (w = XMAX, h = YMAX; w > OX; h -= OY)
{
draw ovalarc (w, h, XC-w/2, YC-h/2, 0, 270);
w -= OX;
draw ovalarc (w, h, XC-w/2, YC-h/2, 270, 90);
addr = gsp_malloc(MAXBYTES);
set_fcolor(GREEN);
seed_fill (XC, YC, addr, MAXBYTES);
gsp_free(addr);
set_videomode(PREVIOUS, INIT);
3-32
TIGA Application Interface
Draw Pie Arc draw-piearc
Syntax
Type
void draw-piearc(w, h, xleft, ytop, theta, arc)
short w, hi
/* width and height
short xleft, ytoPi /* top left corner
short thetai
/* starting angle (degrees)
short arCi
/* angle extend (degrees)
*/
*/
*/
*/
Extended
Description The draw-piearc function draws an arc taken from an ellipse. Two straight
lines connect the two end points of the arc with the center of the ellipse. The
ellipse is in the standard position, with the major and minor axes parallel to
the coordinate axes. The arc and the two lines are all one pixel thick and are
drawn in the current foreground color.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
[:I The width w
[:I The height h
[:I The coordinates of the top left corner (xleft, ytop)
The last two arguments define the limits of the arc:
[:I
The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle, and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
[:I The arc extent, arc, specifies the number of degrees (positive or nega-
tive) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
Example
See patnfill-piearc
3-33
drawJ)oint Draw Point
Syntax
void drawyoint (x, y)
short x, y;
/* pixel coordinates */
Type
Extended
Description The draw-point function draws a single pixel. Arguments x and y give the
XY coordinates of the designated pixel. The pixel is drawn in the current
foreground color.
Example
#include
#include
#include
CONFIG config;
main ()
{
int i, x, y, xy, yx;
if (set_videomode(TIGA, INIT , CLR_SCREEN»
{
if (installyrimitives() >= 0)
{
get_config(&config);
set_fcolor(CYAN);
x = xy = 0;
y = yx = config.mode.disp_vres»l;
/* draw Lissajous pattern in dots
for (i = 1200; i > 0; --i)
*/
{
drawyoint(x+(config.mode.disp_hres»1),
y+(config.mode.disp_vres»1»;
x += yx » 4;
yx -= x » 4;
y += xy » 5;
xy -= y » 5;
set_videomode(PREVIOUS, INIT);
3-34
rIGA Application Interface
Draw Polyline draw-polyline
Syntax
typedef struct
{
short
short
}POINTS;
x;
y;
void draw-Folyline(n, pointu);
short n;
POINTS far *points;
Type
Extended
Description The drawJ)olyline function draws n single pixel-wide lines whose end-
points are supplied in an array of structures, described in the syntax.
Note that for the polygon drawn to be closed, the calling program must ensure that the first and last points are the same.
The function requires two input arguments:
a
a
The first argument, n, defines the number of vertices in the polygon.
The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
The argument points can be of any length. The application can easily
overflow the command buffer used by the host processor to send the
function parameters to the TMS340. The size of the command buffer is in
the CONFIG structure (described in Appendix A) returned by the geCconfig function. The application must check that the data sent will not overflow
this buffer.
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
4
An alternate entry point drawJ)olyline_a with the same parameterization
is supplied to check the size of the data to be sent. If the command buffer
overflows, drawJ)olyline_a attempts to allocate a temporary buffer in
heap. In this way, the application is freed from having to check the size of
the data being transferred; however, the invocation of the function takes
longer, because the length of the data must be parsed. If there is not enough
room to store the temporary buffer in TMS340 memory, the error function
is invoked (which can be trapped by the install_usererror function).
3-35
draw-polyline Draw Polyline
Example
#include
#include
#include
CONFIG config;
/* screen independent coordinates of a cube
short far cube[]
*/
{
-2,+1, -2,-2, -1,-1, -1,+2, -2,+1,
-2,-2, +1,-2, +2,-1, -1,-1, -2,-2,
-1,-1, +2,-1, +2,+2, -1,+2, -1,-1,
};
main()
{
dx, dy, i;
int
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
set_fco1or(MAGENTA);
dx = config.mode.disp_hres»4;
dy = config.mode.disp_vres»4;
/* scale cube coordinates to fit the resolution
for (i = 0; i < sizeof(cube)/sizeof(short); )
*/
{
cube [i++] *= dx;
cube [i++] *= dy;
/* move draw origin to the center of the screen
*/
set_draw_origin(config.mode.disp_hres»l,
config.mode.disp_vres»l);
/* draw the outline of the cube */
draw-polyline«sizeof(cube)/sizeof(short»»l,cube);
set_videomode(PREVIOUS, INIT);
3-36
TIGA Application Interface
Draw Rectangle
,_ _====,~¥..,.,.~::~z~"XX%%::::::::··""",,···
Syntax
Type
...
....
draw_rect
••
··m~:::::::::;:::;m~:::::::::;~~::-" .@..xW..:l';~.:::x::m·;.;e~'::f''''?;::~::~~::::XZ:;-Y..:;:w~:;s:;~::z:»~~~::::;::::::x:;:;x::::::zz~::
void draw_rect(w, h, xleft, ytop)
short w, h;
/* width and height of rectangle
short xleft, ytop;
/* coordinates at top left corner
*/
*/
Extended
Description The draw_reet function draws the outline of a rectangle. The first four argu-
ments define the rectangle:
a
a
a
The width w
The height h
The coordinates of the top left corner (xleft, ytop)
The outline is one pixel wide and is drawn in the current foreground color.
The draw_reet function is equivalent to the following four calls to the
draw_line function:
draw line(xleft, ytop, xleft+w, ytop);
draw-line (xleft, ytop+h, xleft+w, ytop+h);
draw-line (xleft, ytop+l, xleft, ytop+h-2);
draw=line(xleft+w, ytop+l, xleft+w, ytop+h-2);
3-37
field_extract Extract Data from GSP Memory
Syntax
unsigned long field_extract (gptr,fs)
unsigned long gptr;
/* pointer to GSP memory address */
unsigned short fs;
/* field size
*/
Type
Core
Description The field_extract function returns the 32-bit, zero-extended data from the
TMS340 memory address specified by gptr. The field size parameter fs
must be between 1 and 32 inclusive and specifies the number of bits to read
from TMS340 memory. There are no restrictions on the alignment of the
TMS340 address.
3-38
TIGA Application Interface
Insert Data into GSP Memory
field insert
Syntax
void field_insert (gptr,fs,data)
unsigned long gptr;
/* pointer to GSP memory address * /
unsigned short fs;
/* field size
*/
*/
unsigned long data;
/* data to be inserted
Type
Core
Description The field_insert function writes the value of data into the TMS340 memory
specified by gptr. The field size parameter fs must be between 1 and 32
inclusive and specifies the number of bits to be written. Bit 0 (the least
significant bit) of data is written first, followed by bit 1 and so on until the
specified number of bits have been written. There are no restrictions as to
the alignment of the TMS340 address.
3-39
fill_convex
Syntax
Fill Convex Polygon
typedef struct
{
short
short
}POINTS;
X;
y;
void fill_convex(n, points);
short n;
POINTS far *points;
Type
Extended
Description The fill_convex function fills a convex polygon, given a list of points repre-
senting the vertices. To be drawn correctly, the polygon must have at least
three vertices visible. The first and last points must be the same to ensure
that the polygon is closed. The polygon is solid-filled with the current foreground color.
The function requires two input arguments:
Q
The first argument, n, defines the number of vertices in the polygon.
Q
The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
fill_convex is similar to the fillJ)olygon function, but is specialized for rapid drawing of convex polygons. It also executes more rapidly and supports
realtime applications, such as animation.
The fill_convex function automatically culls back faces to support 3-~
applications. A polygon is drawn only if its front side is visible, that is, if it is
facing toward the screen. If the vertices are specified in counterclockwise
order, the polygon is assumed to be facing away from the screen and is
therefore not drawn.
The back face test is done by first comparing vertices n -2, n -1 , and 0 to
determine whether the polygon vertices are specified in clockwise (front
face) or counterclockwise (back face) order. This test assumes the polygon
contains no concavities. If the three vertices are colinear, the back face test
is made again using the next three vertices, n-1, 0, and 1. The test repeats
until three vertices are not colinear. If all the vertices are colinear, the polygon is invisible.
One of the parameters of fill_convex is a list of points that can be of any
length. The application can easily overflow the command buffer used by the
host processor to send the function parameters to the TMS340. The size of
the command buffer is in the CONFIG structure (described in Appendix A)
returned by the geCconfig function. The application must check that the
data sent will not overflow this buffer.
3-40
TIGA Application Interface
Fill Convex Polygon
fill convex
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
4
An alternate entry point fill_convex_a, with the same parameterization, is
supplied to check the size of the data to be sent. If the command buffer
overflows, fill_convex_a attempts to allocate a temporary buffer in heap.
In this way, the application is freed from having to check the size of the data
being transferred; the invocation of the function takes longer, because the
length of the data must be parsed. If there is not enough room to store the
temporary buffer in TMS340 memory, the error function is invoked (which
can be trapped by the instal,-usererror function).
3-41
fill_oval Fill Oval
Synmx
Type
void fill_oval(w, h, xleft, ytop)
short w, h;
/* width, height of recto
short xleft, ytop; /* coordinates of top left corner
*/
*/
Extended
Description The fill_oval function draws an ellipse solid-filled with the current fore-
ground color. The ellipse is in standard position, with its major and minor
axes parallel to the coordinate axes.
The ellipse is defined by the minimum enclosing rectangle in which it is inscribed. The first four arguments define the rectangle:
[Ji The width w
[Ji The height h
[Ji The coordinates of the top left corner (xleft, ytop)
Example
3-42
See draw_oval
TIGA Application Interface
Fill Pie Arc
Syntax
fillJ)iearc
void fill-piearc(w, h, xleft, ytop, theta, arc)
short w, h;
/* width and height
short xleft, ytop; /* top left corner
short theta;
/* starting angle (degrees)
short arc;
/* extent of angle (degrees)
*/
*/
*/
*/
Type
Extended
Description
The fillJ)iearc function draws a pie-shaped wedge solid-filled with the current foreground color. The wedge is bounded by an arc and two straight
edges. The arc is taken from an ellipse in standard position, with its major
and minor axes parallel to the coordinate axes. The two straight edges are
defined by lines connecting the end points of the arc with the center of the
ellipse.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
IJI The width w
IJI The height h
IJI The coordinates of the top left corner (xleft, ytop)
The last two arguments define the limits of the arc:
IJI The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
IJI The arc extent, are, specifies the number of degrees (positive or negative) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
Example
See patnfillJ)iearc
3-43
fill...,polygon Fill Polygon
Syntax
typedef struct
{
short x;
short y;
}POINTS;
void fill-polygon(n, points);
short n;
POINTS far *points;
Type
Extended
Description The fill-po1ygon function fills a polygon, given a list of endpoints of the
polygon. No restrictions are placed on the shape of the polygons filled by
this function: edges can cross each other, filled areas can contain holes, and
two or more filled regions can be disconnected from each other. The polygon is solid-filled with the current foreground color. Note that the first and
last points of the array should be the same to close the polygon.
The function requires two input arguments:
~
The first argument, n, defines the number of vertices in the polygon.
~
The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
This function also takes as an implied argument a 1-bit representation of
the frame buffer, which it uses as a temporary workspace. This workspace
must be set up priorto invoking this function (via a call to the seCwksp function).
The argument points can be of any length. The application can easily
overflow the command buffer used by the host processor to send the
function parameters to the TMS340. The size of the command buffer is in
the CONFIG structure (described in Appendix A) returned by the gecconfig function. The application must check that the data sent will not overflow
this buffer.
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
4
An alternate entry point fill-po1ygon_8, with the same parameterization,
is supplied to check the size of the data to be sent. If the command buffer
overflows fill_polygon_8 attempts to allocate a temporary buffer in heap.
In this way, the application is freed from having to check the size of the data
3-44
rIGA Application Interface
Fill Polygon
fill.J)olygon
being transferred; however, the invocation of the function takes longer
because the length of the data has to be parsed. If there is not enough room
to store the temporary buffer in TMS340 memory, the error function is
invoked (which can be trapped by the install_usererror function).
3-45
fill.J)olygon Fill Polygon
Example
#include
#include
#include
CONFIG config;
/* screen
short far
short far
short far
independent coordinates of a cube
*/
cubel []
{-2,+1, -2,-2, -1,-1, -1,+2, -2, +l) ;
cube2 []
{-2,-2, +1,-2, +2,-1, -1,-1, -2,-2, };
cube3 []
{-1,-1, +2,-1, +2,+2, -1,+2, -1,-1, };
main ()
{
PTR
int
wksp, pitch;
dx, dy, i;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
/* see if wksp allocated
get_config(&config);
if (!get_wksp(&wksp, &pitch»
*/
(
/* workspace not set up in offscreen memory,
*/
/*use rnalloc to create it
*/
pitch = l«lmo(config.mode.disp_hres);
if (pitch < config.mode.disp_hres) pitch «= 1;
wksp = gsp_malloc«(pitch * config.mode.disp_vres)
+
7)
/
8);
set_wksp(wksp, pitch);
dx = config.mode.disp_hres»4;
dy = config.mode.disp_vres»4;
/* scale cube coordinates to fit the resolution
for (i = 0; i < sizeof(cubel)/sizeof(short);
*/
{
cubel[i++]
cubel[i--]
cube2[i++]
cube2[i--]
cube3[i++]
cube3[i++]
3-46
*=
*=
*=
*=
*=
*=
dx;
dy;
dx;
dy;
dx;
dy;
T1GA Application Interface
Fill Polygon
fill-po1ygon
/* move draw orlgln to the centre of the screen
set_draw_origin(config.mode.disp_hres»l,
config.mode.disp_vres»l)j
/* fill in the sides of the cube
set_fcolor(BLUE)j
fill-polygon((sizeof(cubel)/sizeof(short))»l,
cubel)j
set_fcolor(LIGHT_BLUE)j
fill-polygon((sizeof(cube2)/sizeof(short))»1,
cube2)j
set_fcolor(CYAN)j
fill-polygon((sizeof(cube3)/sizeof(short))»1,
cube3)j
*/
*/
set_videomode(PREVIOUS, INIT)j
3-47
---------
-------
---
fill_reet Fill Rectangle
Syntax
Type
void fill_rect(w, h, xleft, ytop)
short w, h;
/* width and height of rectangle
short xleft, ytop /* XY coords at top left corner
*/
*/
Extended
Description The filLrect function draws a rectangle solid-filled with the current fore-
ground color. The first four arguments define the rectangle:
IJ The width w
IJ The height h
IJ The coordinates of the top left corner (xleft,
Example
3-48
ytop)
See bitblt
TIGA Application Interface
Flush External Symbol Table File
Syntax
int flush_esymO
Type
Core
flush esym
Description The flush_esym function does not need to be called by the application. It
is a procedural level interface to the linking loader. It should be used instead
of calling the linking loader directly to provide compatibility with future versions of TIGA.
This function flushes the external symbols from the symbol table
TIGA340. SYM, leaving just the global symbols in this file.
For more details on extensibility and the use of this function, refer to Chapter
4.
If the function terminates correctly zero is returned; if an error occurs, a negative error code is returned. This function returns these error codes:
Error
Code
-1
Description
System Error - Could not find TIGALNK in the main TIGA directory,
either the TIGA environment variable -m option is not set or that
directory does not contain TIGALNK. EXE.
-4
Communications Driver not Running - Run TIGACD
-5
Graphics Manager not Running - Run TIGALNK -lx
-7
Symbol File Error - 1/0 error obtained in accessing symbol file.
The -m option of the TIGA environment variable is not set or the
directory does not contain TIGA340. SYM orthe file is corrupt. In the
latter case, recopy this file from your backup disk.
3-49
flush_extended
Flush All User Extensions
Syntax
void flush_extended ()
Type
Core
Description The flush_extended function performs two operations: first, it flushes the
TIGA extended primitives and the installed user functions (both direct mode
and C-packet) on the TMS340 side. Second, it removes the symbol table
information stored on the host side. You can then install a new set of user
functions.
For more details on extensibility and the use of this function, referto Chapter
4.
3-50
TlGA Application Interface
Fill Frame Oval frame oval
Syntax
Type
void frame_oval(w, h, xleft, ytop, dx, dy)
short w, h;
/* width, height of recto
short xleft, ytop;
/* coordinates at top left corner
short dx, dy;
/* width, height of frame border
*/
*/
*/
Extended
Description The frame_oval function solid-fills an ellipse-shaped frame with the current
foreground color. The frame consists of a filled region between two concentric ellipses. The portion of the screen enclosed by the frame is not altered.
The outer ellipse is specified in terms of the minimum enclosing rectangle
in which it is circumscribed. The first four arguments define the rectangle:
Q The width w
Q The height h
Q The coordinates of the top left corner (xleft,
ytop)
The thickness of the frame in the X and Y dimensions is defined by two additional arguments:
Example
Q
dx specifies the horizontal distance between the outer and inner ellipses.
[J
dy
specifies the vertical distance between the outer and inner ellipses.
See patnfillJ)iearc.
3-51
frame_reet
Syntax
, Type
Fill Frame Rectangle
void frame_rect(w, h, xleft, ytop, dx, dy)
short w, h;
/* width,height of enclosing recto */
short xleft, ytop;
/* coordinates at top left corner */
short dx, dy
/* width, height of frame border
*/
Extended
Description The frame_reet function solid fills a rectangular shaped frame with the cur-
rentforeground color. The frame consists of a filled region between two concentric rectangles. The portion of the screen enclosed by the frame is not
altered.
The outer rectangle is specified in terms ofthe minimum enclosing rectangle
in which it is inscribed. The first four arguments define the rectangle:
[J The width w
[J The height h
[J The coordinates of the top left corner (xleft, ytop)
The thickness of the frame in the X and Y dimensions is defined by two additional arguments:
3-52
[J
dx specifies the horizontal distance between the outer and inner rectangles.
[J
dy specifies the vertical distance between the outer and inner rectangles.
TlGA Application Interface
Return if a Given Function is Implemented
function_implemented
Syntax
int function_implemented(function_code)
short function_code;
Type
Core
Description The function_implemented function queries whether a function is implemented or not. Functions in TIGA have an associated function_code; some
may not be implemented on every board, .
The following functions are not likely to be implemented on all boards and
should be queried with function_implemented before being invoked:
cop2gsp
setyalet
getyalet
setyalet_entry
getyalet_entry
set transp
gsp2cop
inityalet
The function codes themselves are contained in the main TIGA insert file,
which contains the type and function declarations. The function codes are
#defined to be the same as the function name but in upper case. Thus, the
syntax to inquire if set"palet is implemented is
if(function implemented(SET PALET»
{
-
3-53
function_implemented Return if a Given Function is Implemented
. . ~W~55:-~""'~"""mmw,;;;;""""""""",_""",,__
Example
#include
#include
#include
CONFIG config;
main ()
{
short green_index;
if (set_videomode(TIGA, INIT I CLR_SCREEN))
{
/* if it is possible to set the palet entry value,
/* set it to bright green
if (function_implemented(SET_PALET_ENTRY))
*/
*/
green_index = 1;
set.-palet_entry(green_index, 0, OxFF, 0, 0);
else
/* if it is not possible to set the palet entry,
/* (as in the case of a ROM-based palette)
/* then get the index of the brightest green
green_index = get_nearest_color(O, OxFF, 0, 0);
/* use index to clear the screen to
clear_screen(green_index);
set_videomode(PREVIOUS, INIT);
3-54
*/
*/
*/
*/
TlGA Application Interface
Syntax
void get_colors (fcolor, bcolor)
short far *fcolor;
short far *bcolor;
Type
Core
Description The
geCcolors function returns both the foreground and background col-
ors.
3-55
gecconfig Return Board Configuration
Syntax
r
r
r
~
MODEINFO structure definition with the current mode of operation
~
~
typedef struct
{
r
r
r
long dispyitch;
short disp_vres;
short disp_hres
short screen wide
short screen_high;
short dispysize;
long pixel_mask;
short palet_gun_depth;
long palet_size;
short palet_inset;
short numyages;
short num_offscrn_areas;
long wksp_addr;
long wkspyitch;
}MODEINFO;
~
CONFIG structure definition of the current hardware configuration
*/
~
typedef struct
{
short version_number;
long comm_buff_size;
long sys_flags;
long device_rev;
short num_modes;
short current_mode;
long program_mem_start;
long program_mem_end;
long display_mem_start;
long display_mem_end;
long stack_size;
long shared_mem_size;
char far *shared_host_addr;
PTR shared_gsp_addr;
MODE INFO mode;
}CONFIG;
void get_config(config)
CONFIG far *config;
3-56
TIGA Application Interface
Return Board Configuration
Type
geCconfig
Core
Description The gecconfig function returns a structure containing all board- and
mode-specific information. Note that it is very likely that the structure described above will change in subsequent revisions. Therefore, it is recommended that the elements of the structure be referenced symbolically by
their field name, rather than as an offset to the start of the structure. Insert
files are available to do this.
The fields are as follows:
version number
TIGA revision number, assigned by Texas Instruments.
corom buff size
Size, in bytes, ofthe communications buffer; application needs to ensure that tile data sent does not
overflow this buffer, for commands which do not
check the size of the downloaded data.
-
-
Bits 0 - 7 indicate Floating Point Units (FPUs) are
present, in order to be compatible
with the
TMS34020 Coprocessor ID codes. Bits 8 -15 are reserved.
device rev
This function invokes the TMS340's REV instruction
and return its result here.
num modes
Number of extended modes for boards that allow the
switching between different display setups.
current mode
Mode number corresponding to the current operating
mode.
progra~mem_start
Start address of program memory.
program_mem_end
End address of program memory.
display_mem_start Start address of display memory.
display_mem_end
End address of display memory.
stack size
Default stack size can be modified using gsp_minit.
share mem size
Size (in bytes) of shared memory that is available for
the application to use.
share_host_addr
If share_size is nonzero, this is the start address in
host memory of the shared memory; otherwise it is
undefined.
share_gsp_addr
If share_size is nonzero, this is the start address in
TMS340 memory of the shared memory; otherwise,
it is undefined.
3-57
geCconfig Return Board Configuration
dispyitch
Display pitch: linear difference between two scan
lines in bits.
disp_vres
Vertical resolution in scan lines.
disp_hres
Horizontal resolution in pixels.
screen wide
Contains the width of the monitor in centimeters. For
systems where these dimensions are unknown, set
to zero.
screen_high
Contains the height of the monitor in centimeters. For
systems where these dimensions are unknown, set
to zero.
dispysize
Pixel size.
pixel_mask
Contains a mask of the bits used in a pixel. It normally
contains the value of 2 to the power disp""psize minus
1, indicating that every bit of pixel data is pertinent.
On some boards the frame buffer may be arranged
by 8 (dispJ)size = 8) but with only 6 bits implemented.
In that case pixel mask would contain the value 63
(hexadecimaI3F).
palet _gun_depth
Number of bits per gun in palette.
palet_size
Number of entries in the palette.
palet_inset
For most systems this field is set to O. For
TMS34070-based boards that store the palette in the
frame buffer, this is the offset from the start of the scan
line to the first pixel data.
numyages
Number of display pages in multi-buffered systems.
num_off scrn_areas This is the number of offscreen memory blocks avail-
able. If nonzero, then it is used to allocate space for
the offscreen array, which can be obtained from the
TMS340 via a call to the gecoffscreen_memory
function.
Starting linear address in memory of offscreen workspace area.
wkspyitch
Pitch of offscreen workspace area. If wkspJ)itch=O,
then no offscreen workspace is currently allocated.
Example
3-58
TIGA Application Interface
Return Current Cursor State
get curs state
Syntax
Type
Core
Description The geCcurs_state routine returns true (nonzero) if the cursor is enabled.
false otherwise.
Example
See cursor manipulation in set_curs_shape.
3-59
get curs '!-Y
Return Current Cursor Position
Syntax
void get_curs_xy(px, py)
short far *px;
short far *py;
Type
Core
Description The geCcurs_xy returns the pixel coordinates of the cursor hotspot.
Note that the coordinates are relative to the left corner of the screen, not
to the drawing origin.
Example
3-60
See cursor manipulation in seCcurs_shape.
TIGA Application Interface
Return Current Graphics Environment
Syntax
get_env
typedef struet
{
long
xyorigin;
long
pensize;
long
patnaddr;
long
srebm;
long
dstbm;
unsigned long stylemask
}ENVIRONMENT;
void get_env(env)
ENVIRONMENT far *env;
Type
Extended
Description The geCenv function takes as its argument a pointer to the ENVIRON-
MENT structure containing the graphics environment variables. Although
there are functions to manipulate these variables individually, if required,
this function can be used to return the entire environment. Note that the
structure described above may change in subsequent revisions. Therefore,
it is recommended that the elements of the structure be referenced symbolically by their field name, rather than as an offset to the start of the structure.
Insert files are available to do this. The fields of this structure are as follows:
xyorigin
Current drawing origin in y::x format set by seCdraw_origin.
pensize
Current pen size arranged in y::x format, set by setpensize.
patnaddr
TMS340 address of current pattern, set by setJ)atnaddr.
srebm
TMS340 address of current source bitmap structure, set by
seCsrcbm.
dstbm
TMS340 address of current destination bitmap structure, set
by seCdstbm.
stylemask
Current line style mask used by styled_line function.
3-61
geCfontinfo Return Installed Font Information
Syntax
typedef struct
{
char facename[32];
short first;
/*
short last;
/*
short maxwide;
/*
short avgwide;
/*
short maxkern;
/*
short charwide; /*
short charhigh; /*
short ascent;
/*
short descent;
/*
short leading;
/*
long fontptr;
/*
short id;
/*
}FONTINFO;
ASCII code of first character
ASCII code of last character
maximum character width
average width of characters
max character kerning amount
character width (O=proportional)
character height
ascent (how far above base line)
descent (how far below base line)
ldng. (row bottom to next row top)
font address in GSP memory
id of font (set at install time)
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
int get_fontinfo(id, pFontInfo)
short id;
FONTINFO far *pFontInfo;
Type
Core
Description The geCfontinfo function copies a structure of type FONTINFO, which de-
scribes the physical characteristics of the installed font referenced by id
into the structure pointed to by pFontInfo. A nonzero value is returned if
the structure is successfuiiy copied; zero otherwise. An id of zero returns
the FONTINFO structure for the system font, which does not need to be
installed. If id is specified as -1, the FONTINFO of the currently selected
font is returned.
3-62
TlGA Application Interface
Return Interrupt Service Routine Priorities
Syntax
Type
get isr-priorities
void get_isr-priorities(numisrs, ptr)
short numisrs;
/* number of isrs
short far *ptr;
/* pointer to array of shorts
*/
*/
Core
Description The geCisr_priorities function returns the priorities assigned when installing interrupt service routines (ISRs) using the install_rim or install_aim
functions. The calling function must ensure that enough space is allocated
to hold all returned priority information.
There is a one-to-one correspondence between an ISR and its associated
priority. The first priority returned corresponds to the first ISR installed and
so on.
After calling this function, all priority data is flushed internally within TIGA,
thereby enabling new priority data to be collected the next time install_aim
or installJlm is called to install an ISR.
For more details on extensibility and the use of this function, refer to Chapter
4.
3-63
geCmodeinfo Return Board Configuration
Syntax
int get_modeinfo(index, modeinfo)
short index;
MODEINFO far *modeinfo;
Type
Core
Description The gecmodeinfo function returns a structure containing a possible board
configuration supported by the current board and monitor. The MODEINFO
structure is described in detail in the geCconfig function. The index parameter is used to cycle through the different modes by setting it to 0, 1, 2, etc.
It returns the MODEINFO structure for modes 0, 1,2, etc. If an invalid index
is entered, the function returns false (zero); otherwise, it returns true. The
total number of possible modes can be found from the CONFIG structure
using the geCconfig function.
3-64
T1GA Application Interface
Return Nearest Color in
Syntax
long get_nearest_color(r, g, b, i)
char r;
char g;
char b;
char i;
Type
Core
a Palette geCnearesCcolor
Description The geCnearesCcolor function searches the current palette and detects
the closest color value to that specified by the parameters. For a monochrome palette, it is simply the first index closest to i. Forcolor palettes,
the function is more complicated. Weighting values are given to each index
that are the sum of the differences between the parameter r and the color's
red value, and the difference between the parameter g and the color's green
value, etc. Then the index with the smallest weight value is returned. See
also Appendix B.7 for details on color selection.
Example
See function_implemented.
3-65
get_offscreen_memory Return Offscreen Memory Blocks
Syntax
typedef struct
{
long addr;
short xext;
short yext;
}OFF SCREEN_AREA;
void get_offscreen_memory(num_blocks, offscreen)
short num_blocks;
OFF SCREEN AREA far *offscreen;
Type
Core
Description The gecoffscreen_memory function returns the description of the off-
screen memory blocks found in the system for the application to use. These
blocks generally consist of display memory not being used either for the
frame buffer or for an alternate page of frame buffer in multiple buffer systems. The number of blocks is in the structure returned in geCconfig. The
application must reserve enough room for that amount of offscreen entries
by first calling Microsoft's C malloc. The address returned by malloc should
be submitted as the parameter to this function, as well as the number of
blocks to be returned.
The structure returned consists of the start address of the TMS340 offscreen block, plus xext and yext in pixels.
These offscreen blocks can be used as temporary workspace for functions
such as secwksp, seed_fill and zoom_rect. Note that no memory management is performed on these blocks. The application must ensure the validity of the data stored there. Note also that the offscreen memory blocks
are completely separate from those used by the memory managementfunctions such as gsp_malloc.
If an offscreen memory block is used as the default offscreen workspace,
it is guaranteed to be the first block returned via the
gecoffscreen_memory function.
3-66
T/GA Application Interface
Return Offscreen Memory Blocks
Example
#include
#include
#include
#include
geCoffscreen_memory
CONFIG config;
short arrow_shape[]
{
OxOOO3, OxOOO7, OxOOOF, OxOO1F, OxOO3F, OxOO7F, OxOOFF, Ox01FF,
Ox03FF, Ox01FF, OxOO7F, OxOOF7, OxOOF2, Ox01EO, Ox01EO, OxOOCO
};
#define
#define
ARROW W
ARROW H
16
16
main()
{
int i;
PTR arrow_addr;
long arrow_size;
OFF SCREEN AREA far *offscreen;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
arrow_add·r = 0;
/* check if any offscreen areas are big enough
if (config.mode.num_offscrn_areas)
*/
{
/* malloc space in host memory to hold offscreen */
/* structure
*/
offscreen = (OFFSCREEN_AREA *)malloc
(config.mode.num_offscrn_areas
*sizeof(OFFSCREEN_AREA»;
/* get the offscreen memory data structure
*/
get_offscreen_memory(config.mode.num_offscrn_areas,
offscreen);
3-67
gecoffscreen_memory Return Offscreen Memory Blocks
/* define size needed to store the arrow in bits */
arrow_size = ARROW_W * ARROW_H;
for (i = 0; (i < config.mode.num_offscrn_areas) &&
(!arrow_addr); i++)
if «offscreen[il .xext * config.mode.disp-psize)
>arrow_size)
arrow_addr=offscreen[il.addr;
/* if no available offscreen memory, use gsp_malloc */
if (! arrow_addr)
arrow_addr = gsp_malloc«arrow_size+7)/8);
/* transfer shape data from host to gsp
*/
host2gsp«uchar far *) arrow_shape, arrow_addr,
(arrow_size+7)/8, 0);
/* set the source bitmap to the arrow shape
*/
set_srcbm(arrow_addr, ARROW_W, ARROW_W, ARROW_H, 1);
/* blit the arrow to top-left corner of the screen, */
/* performing expand of 1 to n bits-per-pixel
*/
set_colors(LIGHT_GRAY, DARK_GRAY);
bitblt(ARROW_W, ARROW_H, 0, 0, 0, 0);
set_videomode(PREVIOUS, INIT);
3-68
TIGA Application Interface
Read an Entire Palette
Syntax
getpalet
typedef structi
{
char
char
char
char
}PALETi
r:
gi
b:
ii
void get-Falet(palet_size, palet)
short palet_sizei
PALET far *paleti
Type
Core
Description The getJ)alet function reads an entire palette into the palet array. The
parameter should be the same as the entry in the CONFIG
structure to return the entire palette into the palet array defined in host
memory.
palet_size
Note that the palet values returned are the physical colors used in the palette on the board. If a palette hexadecimal entry is set by the setJ)alet or
setJ)aleCentry functions to
Red
FF
Green
= FF
Blue
= FF
Intensity = OF
With the actual color palet using only 4 bits per gun, the hexadecimal values
read by a call to getJ)alet or getJ)aleCentry are
Red
= FO
Green
= FO
Blue
FO
Intensity = 00
See also Appendix B.7 for details on color selection.
Example
See call to geCpaleCentry .
3-69
getJ)alet_entry Return a Palette Entry
Syntax
int get-palet_entry(index, r, g, b, i)
long index;
char far *r;
char far *g;
char far *b;
char far *i;
Type
Core
Description The getJ)aleCentry routine returns the r, g, b, and i entries for a
given entry in the palette. If the index is in the valid range, this function returns true (nonzero) and the palette entry. If the index is invalid, the values
returned are also invalid, and the function returns false (zero).
3-70
TIGA Application Interface
Example
#include
#include
#include
CONFIG config;
main ()
{
char
r, gl, g2, b, i;
if (set_videomode(TIGA, INIT I CLR_SCREEN))
(
if (install-primitives() >= 0)
(
get_config(&config);
if (function_implemented(SET_PALET_ENTRY))
(
/* set two logical colors, shades of green
*/
set-palet_entry(l, 0, OxFF, 0, 0);
set-palet_entry(2, 0, OxFO, 0, 0);
/* get the physical colors back
*/
get-palet_entry(l, &r, &gl, &b, &i);
get-palet_entry(2, &r, &g2, &b, &i);
/* if green values are the same,use blue instead */
i f (gl == g2)
(
set-palet_entry(2, 0, 0, OxFF, 0);
/* fill some rects based on these colors
set_fcolor(l);
fill_rect(config.mode.disp_hres»l,
config.mode.disp_vres»l, 0, 0);
set_fcolor(2);
fill_rect(config.mode.disp_hres»l,
config.mode.disp_vres»l,
config.mode.disp_hres»l,
config.mode.disp_vres»l);
/* restore the palet
init-palet();
*/
*/
set_videomode(PREVIOUS, INIT);
3-71
getJ)ixel Return Pixel Value
Syntax
long get-pixel(x, y)
short x, y; /* coordinates of pixel */
Type
Extended
Description The getj)ixel function returns the value of the pixel at coordinates {x, y}.
The coordinates are relative to the drawing origin. Given a pixel size of n bits,
the pixel is contained in the n LSBs of the return value (the MSBs are as).
3-72
TIGA Application Interface
Return Plane Mask
Syntax
long get ymask ()
Type
Core
getJ)mask
i
Description The getJ)mask function returns the value of the plane mask (GSP PMASK
register). Although only the 16 LSBs of the PMASK register are implemented in the TMS3401 0, the plane mask is 32 bits to provide upward
compatibility with future TMS340 processors.
The plane mask designates which bits within a pixel are protected against
writes, and affects all operations on pixels. The protected bits are replicated
for each pixel throughout the 32-bit plane mask. The 1s in the plane mask
specify protected bits in the destination pixel that cannot be modified, while
the Os specify bits that can be altered. The plane mask can be altered with
a call to the setJ)mask function. See the TMS340 10 User's Guide for a further discussion of plane masking.
3-73
get_ppop Return Pixel Processing Operation
Syntax
int get _ppop ( )
Type
Core
Description The getJ>pop function returns the code for the current pixel processing operation (the PPOP field in the TMS34010's Control register). The 5-bit
PPOP code resides in the 5 LSBs of the return value; all higher order bits
are Os.
The PPOP code determines the manner in which pixels are combined (logically or arithmetically) during drawing operations. A new PPOP code can
be selected with the secppop function. Legal PPOP codes are in the range
oto 21.
Table 3-1. Pixel Processing Options
Code
Replace Destination Pixel with:
Code
Replace Destination Pixel with:
0
source
11
NOT source AND destination
1
source AND destination
12
allis
2
source AND NOT destination
13
NOT source or destination
3
all Os
14
source NAND destination
4
source OR NOT destination
15
NOT source
5
source EQU destination
16
source + destination
6
NOT destination
17
ADDS (source, destination)
7
source NOR destination
18
destination - source
8
source OR destination
19
SUBS (destination - source)
9
destination
20
MAX (source, destination)
10
source XOR destination
21
MIN (source, destination)
The effects of the 22 different codes are described in the TMS34010 User's
Guide.
Example
3-74
See call to seCppop in draw_line.
T1GA Application Interface
Return Text Rendering Attributes
Syntax
int get_textattr(pControl, count, arg)
char far *pControl;
short count;
short far *arg;
Type
Extended
gectextattr
Description The geCtextattr function gets text rendering attributes. pControl is a
control string specifying the attributes to be retrieved. Values associated
with each requested attribute are stored in order in the array specified by
argo The number of attributes in the control string is passed in parameter
count. The number of attributes successfully assigned is returned. This is
the current list of valid attributes:
Attribute Description
%a
alignment
%e
additional intercharacter spacing
Option Value
o = topleft,1 =baseline
16-bit signed integer
3-75
geCtransp Return Transparency
;~;
Syntax
int get_transp();
Type
Core
geCtransp function returns the state of the transparency enable bit
(the T bit from the TMS340's control register). A value of true (nonzero) is
returned if transparency is enabled; otherwise, false (zero) is returned.
Description The
Transparency is an attribute that affects text drawing and pattern fills. If
transparency is enabled, and the result of a pixel processing operation is 0,
the destination pixel is not altered. If transparency is disabled, the destination pixel is replaced by the result of the pixel processing operation, regardless of the value of that result. See TMS340 10 User's Guide for a further discussion of transparency.
3-76
TlGA Application Interface
Get Address at a TMS340 Trap Vector
geevector
_ _ _ _=":>~~~:::;.x~HY~.6%:;::::SS:;:;:M:;:;::::!I:;s:::::l:;!I:;~~~..xx::%xxx:;:::::;:;:,,*,~,,,;**,::x:::::::::;:;:::::::;m
Syntax
unsigned long get_vector (trapnum)
unsigned short trapnum;
Type
Core
geCvector function returns the address currently in the trap vector
specified by trapnum. This function should be used whenever it is necessary to read a trap vector address.
Description The
3-77
geevideomode
....
••
Return Current Emulation Mode
....
_ _" " " _ " " " ' "_ _ _:>,;:l».~~..x%:;m::l:'~;:;~.:::W:;:::::::::;::::':::'-::::::::_·_ _
~::W;:::::::;:::>.::7::::::$:::::::::*;:::::"~H.l:l' m~ .@.·:::::m:.'mW""'«~%";::::~::w::sY'~
Syntax
int get_videomode();
Type
Core
Description
The geCvideomode function returns the current emulation mode. Possible
emulation modes are discussed in the seCvideomode function.
3-78
T1GA Application Interface
Return Windowing Mode
Syntax
int get_windowing();
Type
Core
geCwindowing
Description The geCwindowing function returns the 2-bit windowing code contained
in the control I/O register. The windowing codes are
00
No windowing
01
Interrupt request on write in window
10
Interrupt request on write outside window
11
Clip to window
For a more detailed description of the windowing operation, refer to the
TMS34010 User's Guide.
3-79
geewksp
Return Offscreen Workspace
Syntax
short get_wksp(addr,pitch)
unsigned long *addr;
/* pointer to workspace address
unsigned long *pitch; /* pointer to workspace pitch
Type
*/
*/
Core
Description The geCwksp function returns the parameters defining the current off-
screen workspace. The function returns false(zero} if no offscreen workspace is currently allocated. True (nonzero) is returned if a valid offscreen
workspace is present. If true is returned, then the address and pitch of the
offscreen workspace is returned through the addr and pitch pointer parameters, respectively.
When using functions, such as fill-polygon, that require an offscreen workspace, check for a valid offscreen workspace by calling geCwksp. If none
is present, then allocate one using gsp_malloc and update the workspace
parameters via the seCwksp function.
Example
3-80
See fill-po1ygon.
TIGA Application Interface
Copy from GSP Memory to Coprocessor Memory gsp2cop
Syntax
void gsp2cop (copid,gspaddr, copaddr, length)
short copid;
long gspaddr;
long copaddr;
long length;
Type
Core
Description The gsp2cop function copies data from TMS340 space into the coprocessor space with 10 copid (a number from 0 - 7, with 4 being broadcast,
as defined in the TMS34020 User's Guide). The size of the data to be
transferred is in 32-bit long words.
3-81
gsp2gsp Copy from GSP Memory to GSP Memory
Syntax
void gsp2gsp(addrl, addr2, length)
long addrl;
long addr2;
long length;
Type
Core
Description The gsp2gsp function copies length bytes from TMS340 memory to
TMS340 memory. It handles overlapping regions. There is no restriction on
the alignment of the address.
3-82
TlGA Application Interface
Move Data from GSP Memory to Host Memory gsp2host
~
Syntax
Type
;.~::W..S~~~:;0';:;V":::;~~::::~~::S~:;-;:;:;~X~~":::::::;::-~W.U"::::::X::::::~9;:;~""~'::'~-::::::::''(.X::::::::SX~~~x~~~::t~,~;;:;:;::.,~~~x~;;:;w/g..:;:;:::;:::::~~~~
void gsp2host(gptr, hptr, length, swizzle)
long gptr,
/* GSP memory pointer
char far *hptr;
/* host memory pointer
unsigned short length,/* length in bytes
short swizzle;
/* data SWIZZLE flag
*/
*/
*/
*/
Core
Description The gsp2host function copies length number of bytes from TMS340
memory pointed to by gptr to host memory at hptr.lf swizzle is nonzero,
the data is swizzled before it is written to the host (that is, the order of the
bits in each byte is reversed). gptr is a pointer to TMS340 memory. It must
be byte-aligned (that is, 3 LSBs must be O). hptr is a pointerto host memory.
It must be declared as a long pointer (for example, segmentoffset format).
3-83
gsp2hostxy
Copy Rectangular Memory
Syntax
void gsp2hostxy(saddr, sptch, daddr, dptch, sx, sy, dx, dy,
xext, yext, psize, swizzle)
long saddr;
long sptch;
char far *daddr;
long dptch;
short sx;
short sy;
short dx;
short dy;
short xext;
short yext;
short psize;
short swizzle;
Type
Core
Description The gsp2hostxy function transfers a rectangular area from TMS340 to host
memory. The area is extracted from the source bitmap starting at address
saddr in TMS340 memory and is xext by yext pixels, with the pixel size
being psize. The area starts at coordinates {sx, sy} in the source bitmap
and is transferred to coordinates {dx, dy} of the destination bitmap. Because the host memory address is restricted to be byte address aligned, the
rectangular area sent is always padded on every side {if necessary} to ensure that the data sent is aligned to the nearest byte boundary. The source
pitch, spitch, is the difference in the linear addresses bett.AJeen t'110 pixels
in the same column and adjacent rows of the bitmap in TMS340 memory.
dpitch is the same for host memory.
If swizzle is nonzero, the data is swizzled before it is written to the host
{that is, the order of the bits in each byte is reversed}.
This function has three restrictions placed upon it:
lJI The source pitch {on the TMS340 side}, though a long variable, must
be less than 16 bits.
lJI All data in the host array must be accessible from the segment address
of daddr; that is, none of the data being transferred must have a host
address that crosses segment boundaries.
lJI If data is being swizzled, it is transferred from TMS340 to host and then
transferred back again. The integrity of the data is preserved only if it
is transferred back to the same address it came from. Otherwise, the
data may be garbled.
3-84
TIGA Application Interface
Clear and Allocate GSP Memory gsp_calloc
Syntax
Type
long gsp_calloc(nmemb, size)
long nmemb;
/* number of items to allocate
long size;
'/* size (in bytes) of each item
*/
*/
Core
Description The gsp_calloc function allocates a packet of TMS340 memory large
enough to contain nmemb objects of the specified size and returns a pointer
to it. If it cannot allocate the packet (that is, if it runs outof memory), it returns
a null pointer (0). This function also initiates the allocated memory to all zeros. This function is used in conjunction with gsp_free, gsp_malloc,
gsp_minit, and gsp_realloc.
3-85
gsp_execute Execute a GOFF Program
Syntax
void gsp_execute(entry-point)
unsigned long entry-point;
Type
Core
Description The gsp_execute function is not of general use to a TIGA application but
is included here because the capability to load the graphics manager is an
integral part of TIGA. As a side effect of this TIGA provides a portable COFF
loader across all TMS340 boards. This function executes a program that
has been loaded by the loadcoff function. The parameter entry-point
specifies the start address of the program. On most TMS340 boards, this
address loads into the NMI vector and an NMI is performed.
Example
#include
main (argc, argv)
int
argc;
9har *argv[];
{
unsigned long entry;
if (argc
==
2)
{
if (cd_is_alive(»
{
if (entry = loadcoff(argv[l]»
gsp_execute(entry);
else
printf("Error in load\n");
else printf("TIGACD not running\n");
else printf("Usage: load \n");
3-86
TIGA Application Interface
Free GSP Memory from Allocation
Syntax
int gsp_free (ptr)
long ptr;
Type
Core
gsp free
Description The gsp_free function routine de allocates a packet of TMS340 memory
(pointed to by ptr) previously allocated by gsp_malloc, gsp_calloc, or
gsp_realloc. The function takes no action and returns false (zero) when an
attempt is made to free a packet not previously allocated. This function returns true (nonzero) if the function sucessfu lIy frees a valid TMS340 pOinter.
Example
See draw_ovalarc.
3-87
gsp_malloc
Allocate GSP Memory
Syntax
long gsp_malloc(size)
long size;
/* size (in bytes) of block */
Type
Core
Description The gsp_mallocfunction allocates a packet of TMS340 memory of aspeci-
fied size and returns a pointer to it. If gsp_malloc is unable to allocate the
packet (that is, if it runs out of memory), it returns a null pointer (0). This function does not modify the memory it allocates. This function is used in conjunction with gsp_free, gsp_minlt, and gsp_realloc.
Example
3-88
See fill-po1ygon.
TlGA Application Interface
Return Largest Free Block
Syntax
long gsp_ maxheap ()
Type
Core
gsp_maxheap
Description The gsp_maxheap function returns the size of the largest contiguous
block of program memory for heap allocation. It can be used at the start of
an application to determine the total size of the available memory for heap
allocation. If called during an application, it informs the application of the
largest available block to download an object, for example, a bitmap.
3-89
gsp_minit Reinitialize Dynamic Memory Pool
Syntax
void gsp_minit(stack_size)
long stack size;
Type
Core
Description The gsp_minit function reinitializes and frees all pointers in the TMS340
dynamic memory in the heap pool. Any previously allocated blocks are no
longer allocated, and all pOinters to such blocks become invalid after this
procedure is called. It can also be used to modify the stack_size. The default stack size is defined in the CONFIG structure. Supplying an argument
of -1 selects this stack size. Select a larger/smaller stack by supplying the
stack size in bits.
Be careful using this function because all allocated blocks of memory are
freed, possibly including the background save area for the cursor (if stored
in heap). Disable the cursorpriorto calling this function and install a new cursor via a call to seccurs_shape afterward. If the workspace set by the
secwksp function was previously allocated in heap, it will have to be reset
before using it. gsp_minit also frees data associated with downloaded
extensions and interrupt service routines. Therefore, any required
extensions or interrupt handlers must be reloaded after calling gsp_minit.
This function is used in conjunction with gsp_free, gsp_malloc, and
gsp_realloc.
3-90
TIGA Application Interface
Real/ocate GSP Memory
Syntax
Type
long gsp_realloc(ptr, size)
long ptr;
/* pointer to object to change
long size; /* new size (in bytes) of packet
gsp_realloc
*/
*/
Core
Description The gsp_realloc function changes the size of the allocated data area
pointed to by the first argument, ptr, to the size specified by the second
argument. It returns a pOinter to the space allocated since the packet and
its contents may have to be moved to expand. Any memory freed by this operation is deallocated. If an error occurs, the function returns a zero. This
function is used in conjunction with gsp_calloc, gsp_free, gsp_malloc,
and gsp_minit.
3-91
host2gsp Move Data from Host Memory to GSP Memory
Syntax
Type
void host2gsp(hptr, gptr,
char far *hptr
long gptr;
unsigned short length
short swizzle
length, swizzle)
host memory pointer
GSP memory pointer
length in bytes
data SWIZZLE flag
/*
/*
/*
/*
*/
*/
*/
*/
Core
Description The host2gsp function copies length number of bytes from the host
memory pointed to bYhptr, to TMS340 memory at gptr.If swizzle is nonzero, the data is swizzled before it is written to the TMS340 (that is, the
order of the bits in each byte is reversed). hptr is a pointer to host memory
and must be declared as a long pointer (that is, segment:offsetformat). gptr
is a pointer to TMS340 memory. It must be byte aligned (that is, 3 LSBs must
be 0).
Example
3-92
See gecoffscreen_memory.
rIGA Application Interface
Copy Rectangular Area from Host to GSP
host2gspxy
Syntax
void host2gspxy(saddr, sptch, daddr, dpitch, sx, sy, dx, dy,
xext, yext, psize, swizzle)
char far *saddr;
long sptch;
long daddr;
long dptch;
short sx;
short sy;
short dx;
short dy;
short xext;
short yext;
short psize;
short swizzle;
Type
Core
Description The host2gspxy function transfers a rectangular area from host to TMS340
memory. The area is extracted from the source bitmap starting at address
saddr in host memory and is xext by yext pixels, with the pixel size being
psize. The area starts at coordinates (sx, sy) in the source bitmap and is
transferred to coordinates (dx, dy) of the destination bitmap. Because the
host memory address is restricted to be byte address aligned, the rectangular area sent is always padded on every side (if necessary) to ensure that
the data sent is aligned to the nearest byte boundary.The source pitch,
spitch, is the difference in the linear addresses between two pixels in the
same column and adjacent rows of the bitmap in host memory. The destination pitch dpitch is the same for TMS340 memory.
If swi z z le is nonzero, the data is swizzled before it is written to the TMS340
(that is, the order of the bits in each byte is reversed).
3-93
initjlalet
Default Palette
Syntax
void init-palet()
Type
Core
Description The initpalet function initializes the first 16 entries of the palette to the
EGA default colors:
index
index
index
index
index
index
index
index
0 = Black
1 = Blue
2 = Green
3 = Cyan
4 = Red
5 = Magenta
6 = Brown
7 =Light Gray
index 8 = Dark Gray
index 9 = Light Blue
index 10 = Light Green
index 11 = Light Cyan
index 12 = Light Red
index 13 = Light Magenta
index 14 = Yellow
index 15 = White
The palette may well contain more than 16 entries. If so, this function replicates these 16 colors through the rest of the palette.
Example
3-94
See getJ)aleCentry.
TlGA Application Interface
Initialize Text Drawing Environment
Syntax
void init_text ()
Type
Core
init text
Description The iniCtext function removes all installed fonts from the font table and se-
lects the OEM system font for use in subsequent text operations. It also resets all text drawing attributes to their default state.
3-95
install_aim Install Absolute Load Module
syntax
int install_alm(alm_name)
char far *alm_name; /* load module filename */
Type
Core
Description The install_aim function installs the absolute load module (specified by the
function aIm_name) into theTIGA graphics manager and returns a module
identifier which is used to invoke the extensions specified in the TIGAEXT
section.
If the module contains interrupt service routines, they will be installed into
TIGA, and the priority information associated with each can be retrieved
once installation is complete, with a call to geCisrj)rioritles, which returns
a priority list for last block of ISRs installed. For more details on extensibility
and the use of this function, refer to Chapter 4.
If an error occurs, a negative error code number is returned. Otherwise a
module identifier is returned. This module identifier should be. used whenever a routine contained within this module is specified, by joining the identifier
with the routine number and command type using the bitwise-OR operator
(I).
These are the error codes returned by this function:
Error
Code
Example
3-96
Description
-1
System Error - Could not find TIGALNK in main TIGA directory;
either the TIGA environment variable -m option is not set, or that
directory does not contain TIGALNK. EXE.
-3
Out of Memory - Not enough host memory to run TIGALNK or not
enough TMS340 memory to store ALM.
-4
Communications Driver not Running - Run
-5
Graphics Manager not Running - Run
-8
Missing ALM - Either the spelling of the ALM filename does not
match the ALM filename in the current directory, or the -1 option of
the TIGA environment variable is not set up.
TIGACD
TIGALNK -Ix
See Section 4.3.2 on page 4-8.
TIGA Application Interface
Install Font in Table install font
Syntax
short install_font (pF.ont)
unsigned long pFont;
Type
Extended
Description The install_font function installs the font pointed to by pFont into the font
table and returns an identifier (10) for the font that can be used to reference
the font in subsequent text operations.
Note that pFont is a pointer to a font already located in TMS340 memory.
The InstalLfont function merely adds the address of the font to the font
table. The font must first be loaded from disk by the host and downloaded
intoTMS340 memory. This is shown in the example.
The 10 returned is nonzero if the installation was successful. If unsuccesful,
the reserved 10 for the system font (zero) is returned. For further details on
the font format see Appendix A.
3-97
install_font Install Font in Table
Example
#include
#include
#include
#include
#include
#define FONT MAGIC Ox8040
typedef struct
{
ushort magic;
long
size;
FILEHDR;
/*LOADINST_FONT() Load, install font and return ref. ID
int loadinst_font(name)
char *name;
*/
FILE *fp;
FILEHDR fh;
FONT *hpTmp;
int id = 0;
PTR gpTmp;
/* Examine font hdr. magic num. If incorrect return O.
if (! (fp = fopen( name, "rb"))) return (0);
fread( &fh, sizeof(FILEHDR), 1, fp);
if (fh.magic != FONT_MAGIC)
*/
{
fclose(fp);
return (0);
/*
/*
if
if
Malloc font in host and target. Read font into host, */
then move to target and free host memory.
*/
(hpTmp
(FONT*)malloc«ushort)fh.size))
(gpTmp = (PTR)gsp_malloc( fh.size))
{
rewind(fp);
fread( hpTmp, fh.size, 1, fp);
host2gsp (hpTmp, gpTmp, fh.size, 0);
free( hpTmp);
/* If all is OK, then install the font.
1£ (gpTmp)
id = install_font(gpTmp);
fclose(fp);
return (id);
3-98
*/
TlGA Application Interface
Install Extended Drawing Primitives
Syntax
int installyrimitives ()
Type
Core
install-primitives
Description The install_primitives function is similar to a call to install_rim and is used
to download extended primitives such as draw_line etc. Before calling an
extended primitive download them either by this command, or by installing
a dynamic load module, that includes the primitives. For more details on extensibility and the use of this function, refer to Chapter 4.
If the extended primitives are currently installed when install-primitives is
called, no action is performed.
This function returns these error codes:
Error
Code
Description
-1
System Error - Could not find TIGALNK in main TIGA directory,
either the TIGA environment variable -m option is not set, or that
directory does not contain TIGALNK. EXE.
-3
Out of Memory - Not enough host memory to run TIGALNK or not
enough TMS340 memory to store RLM.
-4
Communications Driver not Running - Run TIGACD.
-5
Graphics Manager not Running - Run TIGALNK -lx
-7
Symbol File Error - I/O error obtained in accessing symbol file.
The -m option of the TIGA environment variable is not set or the
directory does not contain TIGA340. SYM, orthefile iscorrupt.lnthe
latter case, recopy this file from your backup disk.
-10
Symbol Reference - An unresolved symbol was referenced by the
RLM. Determine the name either by producing a link map for the
RLM or by invoking TIGALNK from the command line.
-12
Symbol Table Mismatch - The modules installed in the symbol
table do not match those the TIGA graphics manager has installed.
Reinitialize the modules by a call to flush_extended and install
them again.
3-99
install-primitives Install Extended Drawing Primitives
Example
#include
#include
#include
CONFIG config;
main()
{
/* using INIT_GLOBALS does not initialize the heap,
/* if the primitives were installed they still are
if (set_videomode(TIGA, INIT_GLOBALS I CLR_SCREEN»
*/
*/
{
/* install the optional TIGA extended primitives
if (install-primitives() < 0)
*/
{
printf("Cannot install extended primitives\n");
exit (0) ;
get_config(&config);
set_fcolor(LIGHT_GRAY);
draw_line (0, 0,
config.mode.disp_hres,
config.mode.disp_vres);
set_videomode(PREVIOUS, INIT);
3-100
TIGA Application Interface
Install Relocatable Load Module install_rim
Syntax
int install_rlm(rlm_name)
char far *rlm_name; /* load module filename */
Type
Core
Description The installJlm function installs the relocatable load module (specified by
rlm_name) into TIGA and returns a module identifier that is used to invoke
the extensions specified in the TIGAEXT section.
If the module contains interrupt service routines, they are installed into the
TIGA graphics manager. The priority information associated with each can
be retrieved once installation is complete with a call to the function
geCisrJ)riorities which returns a priority list for the last block of ISRs installed.
If an error occurs, a negative module number is returned. Otherwise a module identifier is returned. This module identifier should be used whenever
a routine contained within this module is specified, by joining the identifier
with the routine number and command type using the bitwise-OR operator
(I).
For more details on extenSibility and the use of this function refer to Chapter
4.
This function returns these error codes:
Error
Code
Description
-1
System Error - Could not find TIGALNK in main TIGA directory,
either the TIGA environment variable -m option is not set or that
directory does not contain TIGALNK. EXE.
-3
Out of Memory - Not enough host memory to run TIGALNK or not
enough TMS340 memory to store RLM.
-4
Communications Driver not Running - Run TIGACD.
-5
Graphics Manager not Running - Run TIGALNK -lx
-6
MisSing RLM - Either the spelling of the RLM filename does not
match the RLM filename in the current directory or the -1 option of
the TIGA environment variable is not set up.
-7
Symbol File Error - 1/0 error obtained in accessing symbol file.
The -m option of the TIGA environment variable is not set or the
directory does not contain TIGA34 0 • SYM or the file is corrupt. In the
latter case, recopy this file from your backup disk.
-10
Symbol Reference- An unresolved symbol was referenced by the
RLM. Determine the name either by producing a link map for the
RLM or by invoking TIGALNK from the command line.
3-101
installJlm Install Relocatable Load Module
Error
Code
-12
Example
3-102
Description (continued)
Symbol Table Mis-match - The modules installed in the symbol
table do not match those the TIGA graphics manager has installed.
Reinitialize the modules by a call to flush_extended and install
them again.
See Section 4.3.1 on page 4-7.
TlGA Application Interface
Install User Error Handler
Syntax
void install_usererror (function_name)
void (far *function_name) ();
Type
Core
install_usererror
Description The instalLusererror function installs a user error function that is called
when an error is found in the host communications. The default usererror
function simply prints a message to the screen when an error occurs. The
user can install another function to trap these errors and handle them accordingly. The user error function expects the following parameters:
usererror(command_number, error_code)
unsigned short command_number;
short error_code;
Current error codes:
Example
1
Timeout with TMS340 communication on trying to load new function; that is, a previous function has not completed.
2
Timeout on waiting for TMS340 function to complete; that is, the
function just invoked has not completed.
3
Parameter allocation failure, not enough memory to allocate a buffer to download data from the current function.
#include
#include
#include
CONFIG config;
#define nofpts 4000
short lotofpts[nofpts*2];
far usererror(command_number, error_code)
unsigned short command_number;
short error_code;
{
printf("TIGA error code of %d in command number %4x\n",
error_code, command_number);
3-103
install_usererror Install User Error Handler
main()
{
int i, x, y;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
install_usererror(usererror);
/* initialize nofpts points to some value
x = y = 0;
for (i = 0; i < nofpts*2;
*/
{
lotofpts[i++]
lotofpts[i++]
i f (i % 4)
x;
y;
{
if (x++ > config.mode.disp_hres)
x = 0;
else
if (y++ > config.mode.disp_vres)
y = 0;
/* set timeout value to 1 second
set_timeout(lOOO);
set-pensize(64,64);
/* tie up the GSP to get timeout since many points
/* are being downloaded, use parameter alloc entry
/* points to allocate a temporary command buffer
/* for the data transfer from host to GSP
pen-polyline_a(nofpts,lotofpts);
/* wait for GSP side to finish (to producetimeouts)
synchronize();
*/
*/
*/
*/
*/
*/
set_videomode(PREVIOUS, INIT);
3-104
TIGA Application Interface
Leftmost One
Syntax
Type
int lmo(n)
long n;
Imo
/* 32-bit integer */
Core
Description The Imo function calculates the bit number of the leftmost one in argument
n. The argument is treated as a 32-bit number whose bits are numbered
from 0 to 31, where bit 0 is the LSB (the rightmost bit position) and bit 31
is the MSB (the leftmost bit position).
For nonzero arguments, the return value is in the range 0 to 31. If the argument is 0, a value of -1 is returned.
Example
See fillJ)olygon.
3-105
loadcoff
Load COFF File
Syntax
unsigned long loadcoff(filename)
char far *filename;
Type
Core
Description The loadcoff function is not of general use to a TIGA application but is
included here because the capability to load the graphics manager is an
integral part of TIGA. With this function TIGA provides a portable COFF
loader across all TMS340 boards. This function loads the COFF file
specified in the parameter. It returns false (zero) if an error occurs during
the load; otherwise, it returns the entry point address of the program.The
entry point can be passed to the gsp_execute function to execute the
COFFfile.
Example
3-106
See gsp_execute.
TIGA Application Interface
Return Status of Page Flipping
Syntax
short page_busy ()
Type
Core
page_busy
Description The page_busy function is used in conjuction with the page_flip function
to determine the status of page flipping. page_busy returns true (nonzero)
if page_flip is called and the pages have not been flipped. Otherwise, false
(zero) is returned.
Example
See page_flip.
3-107
page_flip Set Display and Drawing Pages
Syntax
int page_flip(display, drawing)
short display;
short drawing;
Type
Core
Description The page_flip function can be used if the numyages entry in the CON FIG
structure {described in Appendix A} is greater than 1, indicating that multiple
frame buffers are available in a particular configuration. This function sets
the display page to' display a particular frame buffer and sets the drawing
page for subsequent drawing operations.
The switching of display and drawing pages is performed at the start of vertical blanking.
If the function completes normally, it returns true {nonzero}. If the display or
drawing page is invalid, the function aborts and returns false {zero}.
3-108
TIGA Application Interface
Set Display and Drawing Pages page_flip
Example
#include
#include
#include
#include
#define
#define
#define
#define
#define
#define
#define
#define
TRUE 1
BALL WT 16
BALL HT 16
XMIN 0
YMIN 0
XMAX (config.mode.disp_hres-BALL_WT)
YMAX (config.mode.disp_vres-BALL_HT)
NUM_SPRITES 15
typedef struct
{
short
X;
short
y;
SPRITE;
CONFIG config;
MODEINFO modeinfo;
short display-page = 0;
static SPRITE sprite[NUM_SPRITES];
static short dx[NUM_SPRITES];
static short dy[NUM_SPRITES];
flip-page ()
{
display-page A= 1;
page_flip (display-page, 1-display-page);
init_logic ()
{
register int i;
srand(9);
for (i = 0; i < sizeof(sprite)/sizeof(SPRITE); i++)
{
sprite[i].x = rand()
sprite[i].y = rand()
dx[i]
(rand() % 6)
dy[i] = (rand() % 5)
% (config.mode.disp_hres - 32);
% (config.mode.disp_vres - 32);
+ 1;
+ 1;
3-109
page flip Set Display and Drawing Pages
build_screen ()
{
register int i;
set_fcolor(O);
clear-page(BLACK);
for (i = O;i < sizeof(sprite)/sizeof(SPRITE);i++)
{
set_fcolor(i+l);
fill_oval(16,16,sprite[i) .x,sprite[i) .y);
animate ()
{
register int i;
short tx, ty, tdx, tdy;
for (i = 0; i < sizeof(sprite)/sizeof(SPRITE); i++)
{
tx = sprite [i) .x;
ty = spriteti) .y;
tdx = dx[i);
tdy = dy[i);
if (tx >= XMAX && tdx > 0) tdx = -tdx;
else i f (tx <= Xi:vlIN && tdx < OJ tdx = -tdx;
else i f (ty >= YMAX && tdy > 0) tdy = -tdy;
else i f (ty <= YMIN && dy[i) < 0) tdy = -tdy;
sprite [i) .x += ( dx[i)
tdx ) ;
sprite[i).y += ( dy[i) = tdy ) ;
while (page_busy(»;
build_screen () ;
flipyage () ;
3-110
TIGA Application Interface
Set Display and Drawing Pages page_flip
main()
{
int mode, oldmode;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
oldmode = config.current_mode;
/* look for a mode with more than 1 display page
mode = 0;
do get_mode info (mode, &modeinfo);
while «modeinfo.num-pages == 1) &&
(++mode < config.num_modes»;
if (modeinfo.num-pages > 1)
*/
{
/* set configuration to multiple pages mode
set_config(mode, TRUE);
/* update config structure for current mode
get_config(&config);
flip-page () ;
init_logic();
do animate();
while (!kbhit(»;
getch () ;
*/
*/
if (mode != oldmode)
{
/* restore old mode
set_config(oldmode, TRUE);
clear_frame_buffer(BLACK);
*/
set_videomode(PREVIOUS, INIT);
3-111
patnfill_convex Pattern Fill Convex
Syntax
typedef struct
{
short x;
short y;
}POINTS;
void patnfill_convex(n, points);
short n;
POINTS far *points;
Type
Extended
Description The patnfilCconvex function fills a convex polygon with a pattern, given
a list of points representing the vertices. To be drawn correctly, the polygon
must be convex; that is, it should contain no concavities. A polygon must
have at least three vertices to be visible. To ensure that the polygon is
closed, the first and last vertices should contain the same coordinates. The
polygon is pattern-filled with the current pattern, which is drawn inthe current foreground and background colors.
The function requires two input arguments:
o
o
The first argument, n, defines the number of vertices in the polygon.
The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
The patnfilCconvex function automatically culls back faces to support 3D
applications. A polygon is drawn only if its front side is visible, that is, if it is
facing toward the screen. If the vertices are specified in counterclockwise
order, the polygon "is assumed to be facing away from the screen and is
therefore not drawn.
The back face test is done by first comparing vertices n - 2, n -1 , and 0 to
determine whether the polygon vertices are specified in clockwise (front
face) or counterclockwise (back face) order. This test relies on the polygon
containing no concavities. If the three vertices are colinear, the back face
test is made again using the next three vertices, n -1 , 0, and 1. The test repeats until three vertices are not colinear. If all the vertices are colinear, the
polygon is invisible.
This function is similar to the patnfill-po1ygon function but is specialized
for rapid drawing of convex polygons.
The argument points can be of any length. The application can easily overflow the command buffer which is used by the host processor to send the
function parameters to the TMS340. The size of the command buffer is in
the CON FIG structure (described in Appendix A) returned by the geCcon3-112
TIGA Application Interface
Pattern FiJI Convex patnfill_convex
;
;
fig function. It is up to the application to check that the data sent will not overflow this buffer.
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
4
An alternate entry point patnfill_convex_a with the same parameterization
is also supplied to check the size of the data to be sent. If the command buffer overflows patnfill_convex_a will attempt to allocate a temporary buffer
in heap. In this way, the application is freed from having to check the size
of the data being transferred; however, the invocation of the function takes
longer becuase the length of the data must be parsed. If there is not enough
room to store the temporary buffer in TMS340 memory, the error function
is invoked (which can be trapped by the install_usererror function).
3-113
patnfill_oval Pattern Fill Oval
Syntax
void patnfill_oval(w, h, xleft, ytop)
short w, hi
/* width, height of enclosing recto */
short xleft, ytopi/* XY coordinates of top left corner */
Type
Extended
Description The patnfilLoval function fills an ellipse with the current pattern in the cur-
rent foreground and background colors. The ellipse is in standard position,
with its major and minor axes parallel to the coordinate axes.
The ellipse is defined by the minimum enclosing rectangle in which it is inscribed. Four arguments define the rectangle:
o
o
o
Example
3-114
Thewidthw
The height h
The coordinates of the top left corner (xleft, ytop)
See similar call to patnfill-piearc.
TIGA Application Interface
______
Syntax
Type
~~=,=-
____
Pattern Fill Pie Arc
patnfillj)iearc
-=====_·~~~~~m~~~
void patnfill-piearc(w,
short w, h;
short xleft, ytop;
short theta;
short arc;
h, xleft, ytop, theta, are)
/* width and height
/* top left corner
/* starting angle (degrees)
/* extent of angle (degrees)
*/
*/
*/
*/
Extended
Description The patnfill-piearc function fills a pie-shaped wedge with a pattern. The
wedge is bounded by an arc and two straight edges. The arc is taken from
an ellipse in standard position, with its major and minor axes parallel to the
coordinate axes. The two straight edges are defined by lines connecting the
end points of the arc with the center of the ellipse. The arc is filled with the
current pattern in the current foreground and background colors.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
Q The width w
Q
Q
The height h
The coordinates of the top left corner (xleft, ytop)
The last two arguments define the limits of the arc:
Q
The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
Q The arc extent, are, specifies the number of degrees (positive or negative) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
3-115
patnfill-piearc Pattern Fill Pie Arc
Example
#include
#include
#include
CONFIG config;
/* number of installed patterns
#define PMAX 9
typedef short PAT_ARY[16];
PAT ARY patterns[PMAX]
{
/* PATTERN #
*/
°
*/
{ OxOOOO, Ox3FFC, Ox7FFE, Ox0006, ox0006, Ox1FC6, Ox3FE6,Ox3066,
Ox3066, Ox33E6, Ox31C6, Ox3006, ox3006, Ox3FFE, .Ox1FFC, oxOOOO},
*/
/* PATTERN it 1
{OxOOOO, Ox0080, Ox0080, Ox0080, Ox01CO, Ox01CO, Ox7FFF, Ox1FFC,
OxOFF8, Ox03EO, Ox03EO, Ox07FO, Ox0630, OxOC18, Ox0808, OxOOOO},
/* PATTERN it 2
*/
{ oxoooo, OxOOOO, OxOE38, Ox1F7C, Ox3FFE, Ox3FFE, Ox3FFE, Ox3FFE,
Ox1FFC, OxOFF8, Ox07FO, Ox03EO, Ox01CO, Ox0080, OxOOOO, OxOOOO },
/* PATTERN it 3
*/
{ OxOOOO, ox01CO, Ox19CC, Ox188C, Ox0490, Ox02AO, Ox31C6, Ox3FFE,
Ox31C6, Ox02AO, ox0490, Ox188C, Ox19CC, Ox01CO, oxoooo, OxOOOO },
/* PATTERN it 4
*/
{ Ox0420, Ox0420, Ox3FFC, Ox2424, Ox2424, OxFC3F, Ox2004, Ox2004,
Ox2004, Ox2004, OxFC3F, Ox2424, Ox2424, Ox3FFC, Ox0420, Ox0420 I,
/*
PATTERN
t 5
*/
{ ox0101, Ox0101, Ox8282, Ox7C7C, Ox1010, Ox1010, Ox2828, OxC7C7,
Ox0101, Ox0101, Ox8282, Ox7C7C, Ox1010, Ox1010, Ox2828, OxC7C7 I,
/*
PATTERN it 6
*/
{ oxoooo, OxOOOO, oxOOOO, Ox1FFO, Ox1FFO, OxOABO, Ox1570, OxOABO,
Ox1570, OxOABO, Ox1570, OxOABO, OxOOOO, OxOOOO, OxOOOO, OxOOOO I,
/*
PATTERN it 7
*/
{ OxOOOO, OxFE7F, OxFE7F, OxFE7F, OxFE7F, OxFE7F, OxFE7F, oxoooo,
OxOOOO, Ox7FFE, Ox7FFE, Ox7FFE, Ox7FFE, Ox7FFE, Ox7FFE, OxOOOO I,
/*
*r
PATTERN it 8
{ OxF007, OxF803, Ox9C03, OxOE07, Ox070E, Ox039C, Ox03F8, ox07FO,
OxOFEO, Ox1FCO, Ox39CO, Ox70EO, OxE070, OxC039, OxC01F, OxEOOF I,
};
static short angles[] ={33, 22, 50, 16, 24, 60, 75, 55, 58};
/* Initialize pattern structure
*/
PATTERN patn
{
16,16,1,OL /* width, height, depth, data ptr
*/
};
3-116
TIGA Application Interface
Pattern Fill Pie Arc patnfill-piearc
main ()
{
short w, h, x, y, theta, arc, i;
PTR
gsp-patterns;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
/* allocate space for patterns in GSP memory
gsp-patterns = gsp~alloc(PMAX * sizeof(PAT_ARY»;
/* download patterns from host to gsp
host2gsp «char far *) patterns, gsp-patterns,
PMAX * sizeof(PAT_ARY), 0);
/* setup up with rectangle for the piechart
w
config.mode.disp_hres»l;
h
config.mode.disp_vres»l;
x
config.mode.disp_hres»2;
y
confi~.mode.disp_hres»2;
set_bcolor(BROWN);
set_fcolor(GREEN);
theta = angles[O];
/* draw a piechart with pies filled with patterns
for (i = 1; i < 9; ++i)
*/
*/
*/
*/
{
arc = angles[i];
patn.data = gsp-patterns + «long)i«8);
set-patn«char far*)&patn);
patnfill-piearc(w, h, x, y, theta, arc);
theta += arc;
set_fcolor(CYAN);
frame_oval(w, h, x, y, 2, 2);
set_videomode(PREVIOUS, INIT);
3-117
patnfill-polygon
Syntax
Pattern Fill Polygon
typedef struct
{
short Xi
short Yi
}POINTSi
void patnfill-polygon(n, points)
long ni
POINTS far *points;
Type
Extended
Description The patnfilLpolygon function fills a polygon with a pattern, given a list of
endpoints of the polygon. No restrictions are placed on the shape of the
polygons filled by this function: edges can cross each other, filled areas
can contain holes, and two or more filled regions can be disconnected
from each other. The polygon is filled with the current pattern using the
current foreground and background colors. To ensure that the polygon is
closed, the first and last vertices should have the same coordinates.
The function requires two input arguments:
l::i The first argument, n, defines the number of vertices in the polygon.
l::i The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
This function also takes as an implied argument a 1-bit representation of the
frame buffer, which it uses as a temporary workspace. This workspace must
be set up prior to invoking the patnfillJ)olygon function (via a call to the
se,-wkspfunction).
The argument points can be of any length. The application can easily
overflow the command buffer that is used by the host processor to send the
function parameters to the TMS340. The size of the command buffer is in
the CON FIG structure (described in Appendix A) returned by the ge,-config function. It is up to the application to check thatthe data sent will not overflow this buffer.
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
4
An alternate entry point, patnfillJ)olygon_a with the same parameterization, is also supplied to check the size of the data to be sent. If the command
buffer overflows, patnfilLpolygon_a attempts to allocate a temporary buffer in heap. In this way, the application is freed from having to check the size
3-118
TlGA Application Interface
Pattern Fill Polygon
patnfill.J)olygon
ofthe data being transferred. There is a cost, however, in thatthe invocation
of the function takes longer since the length of the data has to be parsed.
If there is not enough room to store the temporary buffer in TMS340
memory, the error function is invoked (which can be trapped by the install_usererror function)
Example
See call to fill_polygon.
3-119
patnfill reet Pattern Fill Rectangle
Syntax
Type
void patnfill_rect(w, h, xleft, ytop)
short w, hi
/* width and height of rectangle
short xleft, ytoPi /* XY coord at top left corner
*/
*/
Extended
Description The patnfill_reetfunction fills a rectangle with the current pattern in the cur-
rent foreground and background colors. Four arguments define the rectangle:
Il The width w
Il The height h
Il The coordinates of the top left corner (xleft,
Example
3-120
ytop)
See call to fill_reet in fill-po1ygon example.
T/GA Application Interface
Pattern Frame Oval
Syntax
Type
void patnframe_oval(w, h,
short w, hi
/*
short xleft, ytoPi
/*
/*
short dx, dYi
patnframe_oval
xleft, ytop, dx, dy)
width, height of recto
coordinates at top left corner
width, height of frame border
*/
*/
*/
Extended
Description The patnframe_oval function fills an ellipse-shaped frame with a pattern.
The frame consists of a filled region between two concentric ellipses. The
frame is filled with the current pattern in the current foreground and background colors. The portion of the screen enclosed by the frame is not altered.
The outer ellipse is specified in terms of the minimum enclosing rectangle
in which it is inscribed. The first four arguments define the rectangle:
~
~
~
The width w
The height h
The coordinates of the top left corner (xleft, ytop)
The thickness of the frame in the X and Y dimensions is defined by two additional arguments:
Example
~
dx
~
dy specifies the vertical distance
specifies the horizontal distance between the outer and inner ellipses.
between the outer and inner ellipses.
See similar call to frame_oval in patnfilU)iearc example.
3-121
patnframe_rect
Syntax
Type
Pattern Frame Rectangle
void patnframe_rect(w, h, xleft, ytop, dx, dy)
short w, hi
/* width, height of recto
short xleft, ytoPi /* coordinates at top left corner
/* width, height of frame border
short dx, dYi
*/
*/
*/
Extended
Description The patnframe_rect function fills a rectangular frame with a pattern. The
frame consists of a filled region between two concentric rectangles. The
frame is filled with the current pattern in the current foreground and background colors. The portion ofthe screen enclosed by inner edge ofthe frame
is not altered.
The first four arguments define the outer rectangle:
Il The width w
Il The height h
Cl The coordinates of the top left corner (xleft,
ytop)
The thickness of the frame in the X and Y dimensions is defined by two additional arguments:
3-122
Il
dx specifies the horizontal distance between the outer and inner rectangles.
Il
dy specifies the vertical distance between the outer and inner rectangles.
TIGA Application Interface
Pattern Pen Line
Syntax
Type
void patnpen_line(xl, yl, x2, y2)
short xl, yl; /* starting coordinates
short x2, y2
/* ending coordinates
patnpen_line
*/
*/
Extended
Description The patnpen_line function uses the pen to draw a patterned line. Argu-
ments xl and yl specify the starting coordinates of the line, and x2 and y2
specify the ending coordinates.
The pen is a rectangle whose width and height can be modified by means
of the seCpensize function. At each point on the line drawn by the patnpen_line function, the pen is located with its top left corner touching the line.
The area covered by the pen is filled with the current pattern in the current
foreground and background colors.
3-123
patnpen_line Pattem Pen Line
Example
#include
#include
#include
CONFIG config;
/* number of installed patterns */
#define PMAX 8
typedef short PAT_ARY[16];
PAT ARY patterns [PMAX]
{
*/
/* PATTERN # 0
{ OxAAFA, OxFF77 , OxFFFF, OxFF77 , OxAAFA, Ox7070, OxF8F8, Ox7070,
OxFAAA, Ox77FF, OxFFFF, Ox77FF, OxFAAA, Ox7070, OxF8F8, Ox7070 I,
*/
/* PATTERN # 1
{ oxOOCO, Ox0030, OxlF88, Ox2044, ox4024, Ox4E24, Ox9l24, OxAlC4,
Ox2385, Ox2489, ox2472, Ox2402, Ox2204, OxllF8, OxOCOO, Ox0300 I,
*/
/* PATTERN # 2
{ Ox93C9, OxOE70, OxlC38, OxB99D, OxF24F, Ox6666, OxCDB3, Ox4DB2,
Ox4DB2, OxCDB3, Ox6666, OxF24F, OxB99D, OxlC38, OxOE70, Ox93C9 I,
*/
/* PATTERN # 3
{ OxOOOO, Ox7FFE, Ox6426, Ox524A, Ox4992, Ox6666, Ox566A, Ox4992,
Ox4992, Ox566A, Ox6666, Ox4992, Ox524A, Ox6426, Ox7FFE, Oxoooo I,
*/
/* PATTERN # 4
{ Ox044l, Ox8AA2, Ox5114, Ox2388, Ox5114, Ox8442, OxOEEl, OxA54A,
/* PATTERN # 5
*/
{ OxOOOO, Ox60lE, Ox7C3l, Ox2733, Ox29B3, Ox34BO, Oxl2BO, Oxl8BO,
OxOF70, OxOOB2, OxlFF4, Ox7FFC, Ox60lC, Ox403C, Ox5842, Ox3800 I,
*/
/* PATTERN # 6
{ Oxllll, Ox2222, Ox4444, Ox8888, Oxllll, Ox2222, Ox4444, Ox8888,
Oxllll, Ox2222, Ox4444, Ox8888, Oxllll, Ox2222, Ox4444, Ox8888 I,
*/
/* PATTERN # 7
{ ox8888, Ox4444, Ox2222, Oxllll, Ox8888, Ox4444, Ox2222, Oxllll,
ox8888, Ox4444, Ox2222, Oxllll, Ox8888, Ox4444, Ox2222, Oxllll I,
};
*/
/* Initialize pattern structure
PATTERN pattern
{
16,16,1,OL /* width, height, depth, data ptr
*/
};
3-124
TIGA Application Interface
Pattern Pen Line
patnpen line
main()
{
long
long
short
PTR
x, y;
r, t;
fcolor, colormax, patn;
gspyatterns;
if (set_videomode(TIGA, INIT I
CL~SCREEN»
{
if (installyrimitives() >= 0)
{
get_config(&config);
set_draw_origin(config.mode.disp_hres»l,
config.mode.disp_vres»l);
setyensize(4, 3);
/* allocate space for patterns in GSP memory
gspyatterns = gsp_malloc(PMAX * sizeof(PAT_ARY»;
/* download patterns from host to gsp
host2gsp «char far *) patterns, gspyatterns,
PMAX * sizeof(PAT_ARY), 0);
/* initialize colormax variable
colormax = (l«config.mode.dispysize) - 1;
fcolor = 1;
patn
= 0;
/* draw a swirling patterned shape
for (r = 20; r < (config.mode.disp_vres»l);
r += r » 4)
x
=
*/
*/
*/
*/
0;
« 16;
for (t = 0; t < 201; ++t)
y = -r
set_fcolor(fcolor);
if (++fcolor == colormax) fcolor = 1;
if (++patn
== PMAX) patn
= 0;
pattern.data = gspyatterns+«long)patn«8);
setyatn(&pattern);
patnpen_line(x-(x»2»>16, y-(y»2»>16, x»16,
y»16);
x
y » 5;
y += x » 5;
set_videomode(PREVIOUS, INIT);
3-125
patnpen_ovalarc Pattern Pen Oval Arc
Syntax
Type
void patnpen_ovalarc(w,
short w, h;
short xleft, ytop;
short theta;
short arc;
h,
/*
/*
/*
/*
xleft, ytop, theta, arc)
width and height
top left corner
starting angle (degree)
angle extent (degrees)
*/
*/
*/
*/
Extended
Description The patnpen_ovalarc function uses the pen to draw a patterned arc of an
ellipse. The ellipse is in standard position, with the major and minor axes
parallel to the coordinate axes.
The pen is a rectangle whose width and height can be modified by means
of the seCpensize function. At each point on the arc drawn by the patnpen_oval arc function, the pen is positioned so that its top left corner
touches the arc. The area covered by the pen is filled with the current pattern
in the current foreground and background colors.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
[Ji The width w
[Ji The height h
[Ji The coordinates of the top left corner (xleft, ytop)
The last two arguments define the limits of the arc:
[Ji The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle, and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
[Ji The arc extent, are, specifies the number of degrees (positive or nega-
tive) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
Example
3-126
See patnpen_line for use of patterned pen and draw_ovalarc for use oval
arcs.
TIGA Application Interface
Pattern Pie Arc
patnpen_piearc
~~:::::S::~~~;:;::»~~":::::::I:;:;::~f~~mr..::s:»m,;:;:w~.;x:~;%::::%~#.<$.~*;:,;:,*..~m$0m~~~~~
Syntax
Type
void patnpen-piearc(w, h,
short w, h;
/*
short xleft, ytop;
/*
short theta;
/*
short arc;
/*
xleft, ytop, theta, arc)
width and height
top left corner
starting angle (degree)
angle extent (degree)
*/
*/
*/
*/
Extended
Description The patnpenJ)iearc function uses the pen to draw a patterned, pie-shaped
wedge from an ellipse. The wedge is formed by an arc of the ellipse, and
by two straight lines that connectthe two end points of the arc with the center
of the ellipse. The ellipse is in standard position, with the major and minor
axes parallel to the coordinate axes.
The pen is a rectangle whose width and height can be modified by means
of setJ)ensize function. At each point on the arc drawn by the patnpenJ)iearc function, the pen is positioned so that its top left corner touches
the arc. The two lines from the center are drawn in similar fashion. The area
covered by the pen is filled with the current pattern in the current foreground
and background colors.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
Q
Q
Q
The width w
The height h
The coordinates of the top left corner (xleft, ytop)
The last two arguments define the limits of the arc:
Q
The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
Q
The arc extent, are, specifies the number of degrees (positive or negative) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
Example
See patnpen_line for use of patterned pen and similar call to
patnfillJ)iearc.
3-127
patnpen_point
Pattern Pen Point
~~.WXX:;?h5$Wn:;<:;:t
Syntax
Type
void patnpen_point(x ,y)
short x, y; 1* pen coordinates
~Z~W~~N=·
_ _ __
*1
Extended
Description The patnpenj)oint function uses the pen to draw a patterned point. The
resulting figure is a rectangle the width and height of the pen, filled with the
current pattern in the current foreground and background colors. The top left
corner of the rectangle is located at coordinates (x, y).
Example
3-128
See patnpen_llne for use of patterned pen and draw_point for drawing
single pixels.
T/GA Application Interface
Pattern Pen Polyline
Syntax
patnpenJ)olyline
typedef struct points_struct
{
short
short
POINTSi
Xi
Yi
void patnpen-po1yline(n, points)
short ni
POINTS far *pointsi
Type
Extended
Description The patnpen_polyllne function uses the current pen to draw n patterned
lines whose endpoints are supplied in an array of structures, described
in the syntax.
The function requires two input arguments:
[J
The first argument, n, defines the number of vertices in the polygon.
[J
The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
The argument points can be of any length. The application can easily overflow the command buffer that is used by the host processor to send the function parameters to the TMS340. The size of the command buffer is in the
CON FIG structure (described in Appendix A) returned by the geCconfig
function. The application must check that the data sent will not overflow this
buffer.
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
n< -,--------------------4
An alternate entry pOint patnpenj)olyline_a with the same parameterization, is also supplied to check the size of the data to be sent. If the command
buffer overflows patnpenj)olyline_a attempts to allocate a temporary
buffer in heap. In this way, the application is freed from having to check the
size of the data being transferred; however, the invocation of the function
takes longer because the length of the data must be parsed. If there is not
enough room to store the temporary buffer in TMS340 memory, the error
function is invoked (which can be trapped by the instalLusererrorfunction)
Example
See patnpen_line for use of patterned pen and similar call to
draw_polyline for use of polylines.
3-129
peek_breg
Peek B Register
Syntax
long peek_breg (breg)
short breg;
/* B-file register number */
Type
Core
Description The peek_breg function returns the contents of a B-file register. Argument
breg is a register number in the range 0 to 15. The function ignores all but
the 4 LSBs of breg. The return value is 32 bits.
3-130
TIGA Application Interface
Pen Line
Syntax
Type
void pen_line (xl, yl, x2, y2)
short xl, yl;
/* starting coordinates
short x2, y2;
/* ending coordinates
pen_line
*/
*/
Extended
Description The pen_line function uses the pen to draw a line. Arguments xl and yl
specify the starting coordinates of the line; x2 and y2 specify the ending
coordinates.
The pen is a rectangle whose width and height can be modified by means
ofthe setpensize function. At each point on the line drawn by the pen_line
function, the pen is located with its top left corner touching the line. The area
covered by the pen is solid-filled in the current foreground color.
Example
See install_usererror for similar call to penj)olyline.
3-131
pen_ovalarc
Syntax
Type
Pen Oval Arc
void pen_ovalarc(w, h, xleft, ytop, theta, arc)
short w, h;
/* width and height
short xleft, ytop; /* top left corner
short theta;
/* starting angle (degrees)
short arc;
/* angle extent (degree)
*/
*/
*/
*/
Extended
Description The pen_ovalarc function uses the pen to draw an arc taken from an ellipse.
The ellipse is in standard position, with the major and minor axes parallel
to the coordinate axes.
The pen is a rectangle whose width and height can be modified by means
of the seCpensize function. At each point on the arc drawn by the
pen_ovalarc function, the pen is located with its top left corner touching the
arc. The area covered by the pen is solid-filled in the current foreground color.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
Q The width w
Q The height h
Q The coordinates of the top left corner (xleft, ytop)
The last tviiO aiguments define the limits of the aiC:
Q The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
Q The arc extent, arc, specifies the number of degrees (positive or negative) spanned by the angler If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
Example
3-132
See instal,-usererror for use of drawing pen and draw_ovalarc for use of
oval arcs.
T1GA Application Interface
Pen Pie Arc
Syntax
Type
pen-piearc
void pen-piearc(w, h, xleft, ytop, theta, arc)
short w, h;
/* width and height
short xleft, ytop;
/* top left corner
short theta;
/* starting angle (degrees)
short arc;
/* angle extent (degrees)
*/
*/
*/
*/
Extended
Description The pen-f)iearc function uses the pen to draw a pie-shaped wedge from
an ellipse. The wedge is formed by an arc of the ellipse and by two straight
lines that connect the two end points of the arc with the center of the ellipse.
The ellipse is in standard position, with the major and minor axes parallel
to the coordinate axes.
The pen is a rectangle whose width and height can be modified by means
of the set-f)ensize function. At each point on the arc drawn by the
pen-f)iearc function, the pen is located with its top left corner touching the
arc. The area covered by the pen is solid-filled in the current foreground color.
The ellipse from which the arc is taken is specified in terms of the minimum
enclosing rectangle in which it is inscribed. The first four arguments define
the rectangle:
The width w
The height h
Q The coordinates of the top left corner (xleft, ytop)
Q
Q
The last two arguments define the limits of the arc:
Q
The starting angle, theta, is measured from the center of the right side
of the enclosing rectangle, and is treated as modulus 360. Positive
angles are measured clockwise; negative angles are measured counterclockwise.
Q The arc extent, arc, specifies the number of degrees (positive or negative) spanned by the angle. If the arc extent is outside the range
[-359,+359], the entire ellipse is drawn.
Both arguments are expressed in degrees of elliptical arc, with 360 degrees
representing one full rotation.
Example
See install_usererror for use of drawing pen and patnfill-f)iearc for use
of pie arcs.
3-133
pen-.J)oint
Pen Point
Syntax
void pen-point(x, Y)
short X, Yi
/* pen coordinates */
Type
Extended
Description The pen-point function uses the pen to draw a point. The resulting figure
is a rectangle the width and height of the pen and solid-filled with the current
foreground color. The top left corner of the rectangle is located at coordinates (XI y).
Example
3-134
See instalLusererror for use of drawing pen and draw-point for drawing
single pixels.
TIGA Application Interface
Pen Polyline
Syntax
pen-po1yline
,
typedef struct
{
short
short
}POINTS;
X;
y;
void pen-F01yline(n, points);
short n;
POINTS far *points;
Type
Extended
Description The pen-po1yline function uses the current pen to draw lines whose
endpoints are supplied in an array of structures, described in the syntax.
The function requires two input arguments:
o
o
The first argument, n, defines the number of vertices in the polygon.
The second argument, points, is an array in which each pair of adjacent 16-bit quantities contains the X and Y coordinates, respectively, of
a vertex.
The argument point s can be of any length. The application can easily overflow the command buffer used by the host processor to send the function
parameters to the TMS340. The size of the command buffer is in the CONFIG structure (described in Appendix A) returned by the get_config function. The application must check that the data sent will not overflow this buffer.
The number of points that can be sent is given by the following formula:
com_buffer_size (in bytes) - 10
n<
4
An alternate entry pOint pen_polyline_B with the same parameterization,
is supplied to check the size of the data to be sent. If the command buffer
overflows penJ)olyline_a will attempt to allocate a temporary buffer in
heap. In this way the application is freed from having to check the size of
the data being transferred. There is a cost, however, in that the invocation
of the function will take longer since the length of the data has to be parsed.
If there is not enough room to store the temporary buffer in TMS340
memory, the error function is invoked (which can be trapped by the install_usererror function).
Example
See instalLusererror.
3-135
poke_breg
Syntax
Type
Poke B Register
void poke_breg(breg, value)
long breg;
/* B-file register number
short value; /* 32-bit register contents
*/
*/
Core
Description The poke_breg function stores the 32-bit value in a B-file register. Argu-
ment breg is any register number between 0 and 15.
3-136
TIGA Application Interface
Rightmost One
Syntax
Type
int rmo(n)
long n;
rmo
/* 32-bit integer */
Core
Description The rmo function calculates the bit number ofthe rightmost one in argument
n. The argument is treated as a 32-bit number whose bits are numbered
from 0 to 31, where bit 0 is the LSB (the rightmost bit position) and bit 31
is the MSB (the leftmost bit position).
For nonzero arguments, the return value is in the range 0 to 31. If the argument is 0, a value of -1 is returned.
3-137
seed fill
syntax
Type
Seed Fill
int seed_fill(xseed, yseed, buffer, maxbytes)
short xseed, yseed; /* coordinates of seed pixel
long buffer;
/* GSP pointer to working storage
short maxbytes;
/* size of buffer in bytes
*/
*/
*/
Extended
Description The seed_fill function fills a connected region of pixels starting at a speci-
fied seed pixel. The seed color is the color of the specified seed pixel at the
time the function is called. The connected region is solid-filled with the current foreground color.
The first two arguments, xseed and yseed, specify the coordinates of
the seed pixel.
The last two arguments specify a buffer used as a working storage during
the seed fill.
Argument buffer is a buffer large enough to contain the temporary data
that the function uses.
Argument maxbytes is the number of 8-bit bytes available in the buffer
array.
a
a
a
Storage requirements can be expected to increase with the complexity of
the connected region being filled.
Note:
The argument buffer is a pointer in TMS340 memory. This area must have
previously been allocated using gsp_malloc.
The connected region filled by the function always includes the seed pi~el.
To be considered part of the connected region, a pixel must both match:the
seed color and be horizontally or vertically adjacent to another pixel thCiit is
part of the connected region. (A diagonally adjacent neighbor is not sufficient.)
The seed_fill function aborts (returns immediately) if any of these cOhditions are detected:
a
a
a
The seed pixel matches the current foreground ·color.
The seed pixel lies outside the current window register values.
If at any poi'nt the storage buffer space specified by maxbytes is insufficient to continue.
If the function aborts, it returns the value false (zero); otherwise, it completes
normally and returns true (nonzero).
Example
3-138
See draw_ovalarc.
riGA Application Interface
Seed Pattern Fill
Syntax
Type
seed patnfill
int seed-patnfill(xseed, yseed, buffer, maxbytes)
short xseed, yseed; /* coordinates of seed pixel
long buffer;
/* GSP pointer to working storage
short maxbytes;
/* size of buffer in bytes
*/
*/
*/
Extended
Description The seed-patnfill function fills a connected region of pixels with a pattern
starting at a specified seed pixel. The seed color is the color of the specified
seed pixel at the time the function is called. The connected region is filled
with the current pattern in the current foreground and background colors.
Q The first two arguments: xseed, yseed, specify the coordinates of the
seed pixel.
The last two arguments specify a buffer used as a working storage during
the seed fill.
Q Argument buffer is a buffer large enough to contain the temporary data
that the function uses.
Q Argument maxbytes is the number of 8-bit bytes available in the buffer
array.
Storage requirements can be expected to increase with the complexity of
the connected region being filled.
Note:
The argument buffer is a pointer in TMS340 memory. This area must have
previously been allocated using gsp_malloc.
The connected region filled by the function always includes the seed pixel.
To be considered part of the connected region, a pixel must both match the
seed color and be horizontally or vertically adjacent to another pixel that is
part of the connected region. (A diagonally adjacent neighbor is not sufficient.)
The seed-patnfill function aborts (returns immediately) if any of these conditions is detected:
Example
Q The seed pixel matches the current foreground or background color.
Q The seed pixel lies outside the current window register values.
Q If at any point the storage buffer space specified by maxbytes is insufficient to continue.
If the function aborts, it returns the value false (zero); otherwise, it completes
normally and returns true (nonzero).
See similar call to seed_fill in draw_ovalarc.
3-139
selecCfont
Select Installed Font for Use
Syntax
int select_font( id )
short id;
Type
Extended
Description The selecCfont function selects a previously installed font for use by the
text functions. The input argument, id, must be either zero, indicating the
system OEM font, or a value returned by the InstalLfont function.
A nonzero value is returned if the selection was successful, and azero value
if the font referred to by id is not installed in the font table.
3-140
TIGA Application Interface
Set Background C%r
Syntax
void set_bcolor(color)
long color;
Type
Core
set bcolor
Description The seCbcolor function sets the COLORO B-file register to the color index replicated by the pixel size of the current configuration.
Example
See patnfillj)iearc.
3-141
seCclip_rect
Syntax
Type
Set Clipping Rectangle
void set_clip_rect(w,h,xleft,ytop)
short ¥,h;
/* width, height of clipping rect
short xleft,ytop;
/* coordinates of top left corner
*/
*/
Core
Description The secclip_rect function sets the current clipping rectangle by updating
the B-file registers WSTART(B5) and WENO(B6) to the dimensions
specified by the parameters passed. The parameters xleft and ytop are
relative to the current drawing origin.
Example
3-142
See draw_oval.
TlGA Application Interface
Set Foreground and Background Colors set_colors
'"
Syntax
void set_eolors(feolor, beolor)
long feolor;
long beolor;
Type
Core
Description The seCcolors function sets both the COLOR 1 and COLORO 8-file regis-
ters to the color indices replicated by the pixel size of the current configuration.
Example
See geCoffscreen_memory.
3-143
seCconfig
Initialize Graphics Configuration
~~~==
_____ _____
Syntax
int set_config(graphics_mode, init_draw)
short graphics_mode;
short init_draw;
Type
Core
~
=
'%m_$~~_ _ _ _
Description The seCconfig function sets the graphics mode selected by the index
passed to the default graphics mode, in which the board remains until a
subsequent call to set_config is made. Different modes can have different
display resolutions, pixel sizes etc. The gecconfig function can be used
to determine the number of board configurations available on a given board
and the parameters for each configuration. The geCmodeinfo function can
be used to determine the particular configuration parameters for a given
board.To select a particular mode, this function is invoked with an argument
of the desired mode number.
If the graphics_mode argument is valid, the new graphics mode is set up
and the function returns true (nonzero). If the argument is invalid, the function performs no operation and returns false (zero).
This function initializes the following TMS340 registers:
HESYNC to DPYCTL I/O registers
Initialized for the current resolution.
PSIZE I/O register
Set to the current pixel size.
CONVDP I/O register
Set to the left-most-one of the display pitch.
DPYTAP I/O register
Initialized for the board.
DPTCH B-file register
Set to the display pitch.
OFFSET B-file register
Set to the offset of the current drawing page.
WSTART B-file register
Set to O.
WEND B-file register
Set to the disp_vres: disp_hres
value.
If there is an on-board palette, it is reset to the default colors (see
init-palet) .
The seCconfig function also sets the display and drawing pages to page
(for multiple-paged frame buffers).
o
3-144
TlGA Application Interface
Initialize Graphics Configuration
seCconfig
Furthermore if the init_draw flag is set to true (nonzero), the following
drawing environments are initialized:
Q
The transparency is disabled (in CONTROL I/O register)
Q
Window clipping is set (in CONTROL I/O register)
Q
Pixel Processing is set to replace (in CONTROL I/O register)
Q
PMASK I/O register is set to
a
Q Foreground color is set to light grey and the background color to black
Q
Source and destination bitmaps are set to the screen
Q
Drawing origin is set to 0,0
Q Pen width and height are set to 1
Q
Current pattern address is set to 0
Q
All installed fonts are removed and the current selected font is set to
the system font
Q Graphics cursor is set to the center of the screen; it is turned off and
its shape is set to the default shape
Q
Temporary workspace is initialized (see seCwksp)
3-145
seCcurs shape
Syntax
Set Current Cursor Shape
typedef struct
{
short hot_x;
short hot..3;
short width;
short height;
short pitch;
long color;
short mask_rop;
short shape_rop;
PTR data;
}CURSOR;
void set curs_shape(shape);
long shape;
Type
Core
Description The seCcurs_shape function initializes the global pOinter to the cursor
shape with the parameter passed to it (which is a pointer in TMS340
memory). Prior to calling this function, both the cursor shape data and the
cursor structure must be loaded into TMS340 memory using the
gsp_malloc and host2gsp functions. The TMS340 memory address of the
cursor shape data must be assigned to the data element of the cursor
structure before loading the structure. The TMS340 memory address of the
cursor structure can then be passed to this routine to select the cursor. A
default cursor shape (an arrow) is installed with the graphics manager and
is available until this routine is called to download a user cursor. The default
cursor shape can be restored by invoking seCcurs_shape with a
parameter of O.
In the seCcurs_xy function, (x, y) is the position of the top-left pixel of the
cursor if hot _x and hot..3 are zero. These values are subtracted from the
current cursor position to give the top-left hand corner of the cursor starting
drawing point. For example, in a simple crosshairs cursor of width 16 pixels
and height 12 pixels, the hot _xis set to width/2, that is, 8; and similarly,
hot _y is set to 6. If the current cursor position is (320, 240), the rectangle
defining the cursor is drawn with its top left hand corner at 320 - hot _x and
240-hot_y, that is (312, 236). This puts the center of the crosshaircursor
at position (320, 240), the desired cursor position.
The data that defines the cursor consists of (1) cursor mask data, and (2)
cursor shape data. This data defining the cursor shape must be contiguous;
that is, the cursor shape data must immediately follow the cursor mask data.
The pitch of this cursor data is indicated by the pitch element in the
CURSOR structure.
3-146
T1GA Application Interface
Two raster operators, mask_ rop and shape_ rop, determine how the cursor
mask data and cursor shape data, respectively, are expanded onto the
screen. For the mask data, the background and foreground colors are always 0 and OFFFFFFFFh, respectively. The color of the cursor shape is determined by the color element in the CURSOR structure.
An example of cursor data follows. The mask data consists of an array width
by height with Os where the cursor is located and 1s elsewhere. The raster
opforthisdataisAND(1). The shape data is an array width by height with
1s where the cursor is located and Os elsewhere. The rasterop for the shape
data is OR(8). Typically, the shape of the cursor in the mask data is one pixel
wider than that of the shape data. This enables the cursor outline to be seen
when placed over a background of the same color as the cursor shape.
Example masks for a simple cross hair cursor:
11111111111
11110001111
11110001111
11110001111
10000000001
10000100001
10000000001
11110001111
11110001111
11110001111
11111111111
MASKDATA
00000000000
00000000000
00000100000
00000100000
00000100000
00111011100
00000100000
00000100000
00000100000
00000000000
00000000000
SHAPEDATA
3-147
SetCu"entCursorShape
Example
#include
#include
#include
#include
#include
#define ESC OxlB
CONFIG config;
char far PencilData[]=
{
OxFF, Ox87, Ox03, OxOO, OxFF, Ox03, Ox03, Oxoo, OxFF, Ox03, Ox02, OxOO, OxFF, Ox01, Ox02, OxOO,
OXFF, OX01, OX03, OXOO, OXFF, OXOO, OX03, OXOO, OXFF, OX80, OX03, OXOO, OX7F, OX80, OX03, OXOO,
Ox7F, Oxcc, Ox03, Oxoo, Ox3F, Oxcc, Ox03, Oxoo, Ox3F, axED I Ox03, OxOO, OxlF, OxED, OxO 3, OxOO,
OxIl!' I OxFO, Ox03, OxOO, OxOF I OxFO, Ox03, OxOO, OxOF, OxFa, Ox03, OxOO, Ox07, OxF8, Ox03, OxOO,
Ox07, OxFC, Ox03, OxOO, Ox03, OxFC, Ox03, OxOO, Ox03, OxFE, Ox03, OxOO, Ox01, OxE'E, Ox03, OxOO,
Ox01, OxFF, Ox03, OxOO, OxOO, OxFF I Ox03, OxOO, Ox80, OxFF I Ox03, OxOO, OxCC, OxFF I OxO], OxOO,
OxED, OxFF, Ox03, OxOO, OxFO, OxFF, Ox03, OxOO, OxE'S, OxFF, Ox03, OxOO, OxFD, OxFF, Ox03, OxOO,
OxOO, OxOO, OxOO, OxOO, OxOO, Ox'78, OxOO, OxOO, OxOO, OxFS, OxOO, OxOO, OxOO, OxFC, OxOO I OxOO,
OxOO,Ox7C,OxOO,Oxoo,OxOO,Ox72,OxOO,Oxoo,OxOO,Ox26,OxOO,Oxoo,OxOO,Ox39,OxOO,Oxoo,
Oxoo, Ox11, OxOO, Oxoo, Ox80, Ox10, Oxoo, Oxoo, Ox80, Ox08, Oxoo, OxOO, Ox40, Ox08, OxOO, Oxoo,
Ox40, Ox04, Oxoo, Oxoo, Ox20, Ox04, Oxoo, Oxoo, Ox20, Ox02, Oxoo, Oxoo, Ox10, Ox02, OxOO, OxOO,
Ox10, Ox01, Oxoo, Oxoo, Ox08, Ox01, Oxoo, Oxoo, Ox88, Oxoo, Oxoo, OxOO, Ox84, Oxoo, Oxoo, Oxoo,
Ox44, Oxoo, Oxoo, Oxoo, Ox4E, Oxoo, 0';00, Oxoo, Ox3E, Oxoo, Oxoo, Oxoo. Ox1E, Oxoo. OxOO, Oxoo,
OxOE, Oxoo, Oxoo, Oxoo, Ox06, Oxoo, Oxoo, Oxoo, Ox02, Oxoo, Oxoo, OxOO, Oxoo, Oxoo, OxOO, Oxoo
};
CURSOR far pencil =
{OxOOOO, Ox001B, OxOOll, Ox001C, Ox0020, OxOFL, 1, 8, OL};
struct
short x,y;
/* coordinates
short left, right; /* buttons
short xl, yl, x2,y2; /* boundary
}mouse;
*/
*/
*/
union REGS regs;
3-148
TlGA Application Interface
SetCu"entCu~orShape
set_curs_shape
/* checks for an installed mouse driver
check_mouse()
{
regs.x.ax = 0;
int86(Ox33,®s,®s);
return(regs.x.ax);
*/
mouse_driver()
/* get mouse coordinates
regs.x.ax = 11;
int86(Ox33,®s,®s);
mouse.x += regs.x.cx;
mouse.y += regs.x.dx;
/* ensure the mouse stays within the screen boundary
if (mouse.x < mouse.x1)
mouse.x = mouse.x1;
if (mouse.x > mouse.x2)
mouse.x = mouse.x2;
if (mouse.y < mouse.y1)
mouse.y = mouse.y1;
if (mouse.y > mouse.y2)
mouse.y = mouse.y2;
/* tell the GSP cursor*/
set_curs_xy(mouse.x, mouse.y);
/* get the mouse buttons */
regs.x.ax = 3;
int86(Ox33,®s,®s);
mouse. left
regs.h.bl & 1;
mouse.right = (regs.h.b1 & 2) » 1;
*/
*/
~149
seccurs_shape
Set Current Cursor Shape
install_cursor (type)
short type;
/* O=default(arrow), l=user(pencil)
*/
{
*/
/* Address of user cursor in GSP mem
static PTR UserCurs = OL;
if (type)
{
/* User cursor type specified
if( UserCurs == OL )
*/
{
/* Execute this block 1st time only
unsigned short num_bytes;
/* download cursor shape data to GSP
num_bytes=({pencil.height * pencil.pitch) « 1) »
pencil.data=(PTR)gsp_malloc(num_bytes);
host2gsp (PencilData, pencil.data, num_bytes, 0);
/* download cursor structure to GSP
num_bytes=sizeof(CURSOR);
UserCurs=(PTR)gsp_malloc{num_bytes);
host2gsp (&pencil, UserCurs, num_bytes, 0);
*/
*/
3;
*/
set_curs_shape( UserCurs );
else
set_curs_shape ( (PTR) 0);
/*Use default if type==O
*/
maine)
{
char key;
short CursorType=l;
if (check_mouse(»
{
if (set_videomode{TIGA, INIT I CLR_SCREEN»
{
if (insta1l-Frimitives{) >= 0)
{
get_config(&config);
printf("Press ... \n");
printf("
ESC to quit\n");
printf("
SPACE to toggle cursor shapes\n");
printf("
LEFT mouse button to draw points\n");
/* assign a new cursor shape
*/
install_cursor(CursorType);
3-150
T1GA Application Interface
Set Current Cursor Shape
set curs shape
/* initialize mouse to the center of the screen
mouse.x=config.mode.disp_hres»l;
mouse.y = config.mode.disp_vres»l;
set_curs_xy(mouse.x, mouse.y);
/* intialize mouse boundary
mouse.x1
mouse.y1 = 0;
mouse.x2 = config.mode.disp_hres - 1;
mouse.y2 = config.mode.disp_vres - 1;
/* turn on cursor
set_curs_state(l);
for (; i)
*/
*/
*/
{
/* move the cursor with the mouse
mouse_driver () i
/* if left button pressed draw a point
if (mouse.left)
draw-point(mouse.x, mouse.y)i
i f (kbhit () )
switch ( getch ()
*/
*/
{
case I , :
install_cursor(CursorType A =l)i
break;
case ESC :
set_curs_state(O); /* Turn cursor off
set_videomode(PREVIOUS,INIT)i
exit (0) ;
*/
set_videomode(PREVIOUS,INIT);
else printf("Mouse driver required for this example\n");
3-151
seCcurs state
Set Current Cursor State
Syntax
void set_curs_state(enable)
short enable;
Type
Core
Description The seCcurs_state function displays the cursor (if enable is nonzero) or
removes it from the screen.
Example
3-152
TIGA Application Interface
Set Current Cursor Position
Syntax
void set_curs_xy(x, y)
short x;
short y;
Type
Core
seccurs_xy
Description The seCcurs_xy function modifies the pixel coordinates of the cursor's
hotspot.The cursor coordinates are not relative to the drawing origin; they
are always relative to the top left hand corner of the screen.
Example
See seCcurs_shape.
3-153
set_draw origin
Set Drawing Origin
Syntax
void set_draw_origin{x, y)
short Xi
short Yi
Type
Extended
Description The seCdraw_origin function sets the drawing origin for all subsequent
drawing functions. All coordinates specified for all drawing functions are relative to the drawing origin.
Example
3-154
See styled_line.
TlGA Application Interface
Set Destination Bitmap
Syntax
void set_dstbm(addr,pitch,xext,yext,psize)
long addr;
short pitch;
short xext;
short yext;
short psize;
Type
Extended
seCdstbm
Description The seCdstbm function sets the TMS340's destination bitmap for subsequent bitblt or drawing functions. Invoking the function with an address
of 0 sets the destination bitmap to the screen.
The pitch of the destination bitmap must be a multiple of 16. Currently, no
clipping is performed in a linear bitmap; the calling program must do this.
Future TIGA revisions will provide this capability.
3-155
set dstbm
EXalnple
Set Destination Bitmap
#include
#include
#include
CONFIG config;
/* function to save portion of screen defined by arguments*/
/* into a linear bitmap and return the address
*/
unsigned long save_offscreen(width, height, x_left, y_top)
short width, height, x_left, y_top;
{
unsigned long address;
address = (PTR) gsp_malloc(((long)width * (long)height *
(long) config.mode.dispysize) /8);
if (address)
{
/* turn off transparency, otherwise pixels of 0 color */
/* will not be copied into the destination bitmap
*/
transp_off () ;
set_srcbm(Ol,O,O,O,O);
set_dstbm(address, width * config.mode.dispysize,
width, height, config.mode.dispysize);
bitblt(width, height, x_left, y_top, 0, 0);
set_dstbm(Ol,O,O,O,O);
return(address);
/* function to restore to the screen a pre-saved
/* rectangular region in heap pointed to by address
restore_onscreen(address, width, height, x_left, y_top)
unsigned long address;
short width, height, x_left, y_top;
*/
*/
{
if (address)
{
/* turn off transparency, otherwise pixels of 0 color */
/* will not be copied into the destination bitmap
*/
transp_off () ;
set_srcbm(address, width * config.mode.dispysize,
width, height, config.mode.dispysize);
set_dstbm(Ol,O,O,O,O);
bitblt(width, height, 0, 0, x_left, y_top);
set_srcbm(Ol,O,O,O,O);
3-156
TIGA Application Interface
Set Destination Bitmap
secdstbm
main ()
{
short w, h, x, y, i;
PTR
save;
if (set_videomode(TIGA, INIT I CLR_SCREEN))
{
if (install-primitives() >= 0)
{
get_config(&config);
clear_screen(LIGHT_MAGENTA);
w
config.mode.disp_hres»4;
h
config.mode.disp_vres»4;
x
config.mode.disp_hres»2;
y
config.mode.disp_vres»l;
/* save a portion of the screen
*/
save = save_offscreen(w, h, x, y);
/* clear screen to the current background color
*/
clear_screen(-l);
x = y = 0;
/* restore saved region to various places on screen*/
for (i = 0; i < 8; i++)
{
restore_onscreen(save, w, h, x, y);
x += config.mode.disp_hres»3;
y += config.mode.disp_vres»3;
gsp_free(save);
set_videomode(PREVIOUS, INIT);
3-157
set_feolor
Set Foreground Color
Syntax
void set_fcolor (color)
long color;
Type
Core
Description TheseCfcolorfunction sets theCOLOR1 B-fileregistertothecolor index
replicated by the pixel size of the current configuration.
Example
3-158
See fillJ)olygon.
TlGA Application Interface
Set Interrupt Handler
seCinterrupt
Syntax
void set_interrupt (level, priority, enable, scan_line)
short level;
short priority;
short enable;
short scan_line;
Type
Core
Description The seCinterrupt function enables/disables a previously installed interrupt
service routine. The routine must have been installed via the install_rim
function or the combination of create_aim and install_aim.
The level parameter indicates the interrupt level where the interrupt routine was installed. The priori ty is returned by the geCisr_priorities function when the interrupt is installed, to distinguish between different interrupt
service routines on the same interrupt level. If enable is true (nonzero), the
interrupt is enabled; otherwise, it is disabled.
The scan_line parameter is valid only for display interrupts (interrupt level
10). It is used to set the line at which the interrupt occurs. If the scan_line
parameter is -1 , then the value for the s can_line is taken to be that passed
in the previous invocation of seCinterrupt. This allows the interrupt to be
enabled/disabled without re-specifying the scan_line parameter.
For more details on extensibility and the use ofthis function, refer to Chapter
4.
Example
See Section 4.9.
3-159
set-palet
Initialize a Palette
Syntax
typedef struct
{
char ri
char gi
char bi
char ii
}PALETi
void set-palet(count, index, palet)
long counti
long indexi
PALET far *paleti
Type
Core
Description The set.J)alet function loads the palette on the board using the palet
array. The number of palette entries to be loaded is passed in argument
count. Argument index designates where the palette loading is to start.
This allows for a palette to be loaded one piece at a time, rather than all at
once. The range that is being loaded is checked by this function to ensure
that it does not overflow the palette; thus, if the starting index plus the
number of entries (count) is greater than the palette size, the count value
is decreased by the appropriate amount.
In the PALET structure, r, g, and b refer to the red, green, and blue
values for the color entry (0 being off and all1s being full on); i is an intensity level for monochrome displays. See also Appendix B.7 for details on color
selection.
On systems that store the palette data in display memory (such as those using the TMS34070), this function reloads every palette data area in the frame
buffer. Thus, if the system contains multiple display pages, every page is
loaded by this function.
Example
3-160
See similar call to set.J)aleCentry.
TlGA Application Interface
Set a Palette Entry
Syntax
int set-palet_entry(index, r, g, b, i)
long index;
char r;
char g;
char b;
char i;
Type
Core
set-paleCentry
Description The set"paleCentry function initializes one entry index in a palette. If the
function aborts, it returns the value false (zero); otherwise, it completes normally and returns true (nonzero).
In the palette structure, r, g, b refer to the red, green and blue values for
the color entry (0 being off and all1s being full on), and i is an intensity
level for monochrome displays. See also Appendix B.7 for details on color
selection.
On systems that store the palette data in display memory (such as those using the TMS34070) this function reloads the palette entry in every palette
data area in the frame buffer. Thus if the system contains multiple display
pages, every page is loaded by this function.
Example
See get-paleCentry.
3-161
m-________________
___
set--patn
Set Current Pattern Address
~
Syntax
_ =_ _ _ _ _ _ _
• _ _ _ _ _ _ _ _ _ _ _ __
typedef structure
ushort width;
ushort height;
ushort depth;
PTR data;
PATTERN;
void set patn(p)
PATTERN far *p;
Type
Extended
Description The set_patn function sets the current drawing pattern as specified by the
PATIERN structure pointed to by p. Currently, only 16 x 16 x 1 patterns are
supported in TIGA's extended graphics primitives. The application mustfirst
install its pattern data using gsp_malloc to allocate TMS340 storage
memory and then use host2gsp to transfer them to TMS340 memory. A
pointer to the desired pattern in TMS340 memory is then set in the PATTERN structure before calling setJ)atn.
Example
3-162
See patnfillJ)iearc.
T1GA Application Interface
Set Pensize
Syntax
void set-pensize(w, h)
short w, h; /* pen width and height */
Type
Extended
setJ)ensize
Description The set,J)ensize function specifies the width and height of a rectangular
pen. These dimensions are used for any subsequent drawing operations
with the pen.
Example
See install_usererror.
3-163
set-pmask
Set Plane Mask
Syntax
void setymask (mask)
long pmask;
/* plane mask */
Type
Core
setj)mask function specifies the plane mask that is used in subsequent drawing operations. The mask determines which bits in a pixel can
be modified during drawing operations. The Os in the mask enable modification ofthe corresponding bit planes. The 1s in the mask write-protectthe corresponding planes.
Description The
The plane mask designates which bits within a pixel are protected against
writes and affects all operations on pixels. The protected bits are replicated
for each pixel throughout the 32-bit plane mask. The 1s in the plane mask
specify protected bits in the destination pixel that cannot be modified, while
the Os specify bits that can be altered. The plane mask can be read by
means of a call to the getj)mask function. See the TMS34010 User's
Guide for a further discussion of plane masking.
3-164
TIGA Application Interface
Set Pixel Processing Operation
secppop
Syntax
void set_ppop (ppop_code)
short ppop_code; /* pixel processing operation code */
Type
Core
Description The seCppop function defines the pixel processing operation for subsequent drawing operations. The specified Boolean or arithmetic operation
determines the manner in which source and destination pixel values are
combined. The rangeforthe ppop_code argument is Oto 21. The codes are
described in the following table:
Table 3-2. Pixel Processing Options
Code
Replace Destination Pixel with:
Code
Replace Destination Pixel with:
0
source
11
NOT source AND destination
1
source AND destination
12
all1s
2
source AND NOT destination
13
NOT source or destination
3
all Os
14
source NAND destination
4
source OR NOT destination
15
NOT source
5
source EQU destination
16
source + destination
6
NOT destination
17
ADDS (source, destination)
7
source NOR destination
18
destination - source
8
source OR destination
19
SUBS (destination - source)
9
destination
20
MAX (source, destination)
10
source XOR destination
21
MIN (source, destination)
The TMS34010 User's Guide (literature number SPVU001) describes the
details of these operations.
Example
See draw_line and zoom_reet.
3-165
seCsrcbm
Set GSP's Source Bit Map
Syntax
void set_srcbm(addr,pitch,xext,yext,psize)
long addr;
short pitch;
short xext;
short yext;
short psize;
Type
Extended
Description The seCsrcbm function sets the TMS340's source bitmap for subsequent
bitblt functions. Invoking the function with the address of 0 sets the source
bitmap to the screen.
The pitch of the source bitmap must be a multiple of 16. Currently no clipping
is performed in a linear bitmap, the calling program must do this. Future
TIGA revisions will provide this capability.
Example
3-166
See seCdstbm.
TIGA Application Interface
.
Set Text Rendering Attributes
Syntax
int set_textattr(pControl, count, arg)
char far *pControl;
short count;
short far *arg;
Type
Extended
seCtextattr
Description The seCtextattrfunction sets text rendering attributes. pControl is a control string specifying the attributes to be set. Values associated with attributes can be specified either as immediate values in the control string. or as
arguments passed in the array argo The number of attributes in the control
string must be passed in parameter count.
When a values is passed as a string literal, it should be placed between the
%character and the attribute. For example, to assign the value 1 to attribute
a enter:
set_textattr (l%la", I, 0);
To pass the same value as an argument, an asterisk is placed between the
% character and attribute, and the value 1 is provided as the first argument
(element 0) in the passed array:
short arg[l];
arg[O] = 1;
set_textattr("%*a", I, arg[O]);
The number of attributes successfully set is returned. This is the current list
of valid attributes:
Attribute Description
%a
alignment
%e
additional intercharacter spacing
Option Value
= top left,1 = baseline
16 bit signed integer
o
3-167
seCtimeout Set Timeout Delay Value
Syntax
void set_timeout (value)
short value; /* value in milliseconds */
Type
Core
Description The seCtimeout function sets the value of the timeout value (in milliseconds) that determines how long the host waits for a TMS340 function to
complete prior to calling the error function with a timeout. The user can ignore timeouts altogether by installing a user error handler function that is
called when the timeout occurs. This function can be made to ignore such
timeouts.
Example
3-168
See instalLusererror.
TIGA Application Interface
Set Transparency Mode
Syntax
void set_transp(mode)
short mode;
Type
Core
seCtransp
Description The seCtransp function, if implemented (on TMS34020 systems only),
changes the transparency mode. Currently, these are the modes supported
are:
mode = 0
Transparency on source equals zero
mode = 1
Transparency on source equals COLORO
mode = 2
Transparency on result equals zero
mode =3
Transparency on result equals COLORO
On TMS3401 0 systems, only mode 2 is supported.
3-169
seCvector
Set Contents of GSP Trap Vector
Syntax
unsigned long set_vector(trapnum, newaddr)
unsigned short trapnum;
unsigned long newaddr;
Type
Core
Description The
seCvector function writes the specified 32-bit address contained in
newaddr into the trap vector specified by trapnum. The address originally
in this trap is returned. This function should be used whenever it is necessary to modify a trap vector address.
3-170
TIGA Application Interface
Set Emulation Mode
Syntax
int set_videomode(mode, style)
short mode;
short style;
Type
Core
seCvideomode
Description The seCvideomode function sets up the video mode to be used. Every
TIGA application should start with a call to this function with a mode of TIGA
and the initialize flag set (non-zero) prior to invoking any other TIGA function. This function sets up the mode to be used in a particular application.
These are the valid modes:
TIGA
MDA
HERCULES
CGA
EGA
VGA
AI 8514
PREVIOUS
All TIGA applications should call seCvideomode with TIGA mode upon
starting. They should then call seCvideomode again at the end of their program to restore IBM emulation (since in most cases the board on which
TIGA is being run is the primary video board). The mode selected could be
PREVIOUS which restores the emulation mode from a global. However, if a
particular application wants to switch back and forth between several
modes, it is recommended that a call be made to geCvideomode and the
mode be saved by the application. The saved mode can be used to terminate
the TIGA application and to restore the board to the initial state.
If a call is made to seCvideomode and that particular video mode is not
supported by the board, the routine returns false (zero).
The style parameter is used to determine the manner in which the mode
is set up in on entry. This list describes valid styles:
NO_INIT
Used during an application to switch between TIGA and
other emulation modes. It enters TIGA, leaving all global
variables intact.
INIT_GLOBALS
Initializes the global variables only, by calling
seCconfig with the iniCdraw flag true and by restoring
the timeout value and the user error handler. The heap
pool is retained, which keeps the downloadable extensions installed.
INIT
Initializes global variables and dynamic memory (heap
pool).This frees all allocated pointers and thus deletes
all downloaded extensions.
3-171
seCvideo mode
Set Emulation Mode
. ---===-.,,"""""""""""'"""""--
The style parameter contains one further option, which can be selected by
ORing with the above style parameter:
CLR_SCREEN
3-172
This parameter should be used at initialization when you
are using the INIT_ GLOBALS or INIT styles. The screen
is blanked while the video registers are initialized.
TIGA Application Interface
Set Windowing Mode
Syntax
void set_windowing(enable)
short enable;
Type
Core
seCwindowing
Description The seLwindowing function sets the two-bit windowing code contained in
the CONTROL 1/0 register. The windowing codes are
[J 00 - No windowing
[J 01 - Interrupt request on write in window.
[J
10 - Interrupt request on write outside window.
[J
11 - Clip to window.
For a more detatiled description of the windowing operation, refer to the
TMS34010 User's Guide (literature number SPVU001). Care must be taken
in using this function. The extended drawing primitives assume windowing
option 3 (clip to window) is set. Setting the interrupt request modes (1 and
2) should only be done after downloading an interrupt service routine for the
window violation interrupts (see Installing Interrupts in Chapter 4).
3-173
secwksp
Syntax
Type
Set a Temporary Workspace
void set_wksp(addr, pitch)
unsigned long addr; /* starting address
unsigned long pitch;/* workspace pitch
*/
*/
Core
Description The seCwksp function sets the workspace environment variables to the
specified address and pitch. The workspace memory is used by functions
such as filljlolygon to draw a 1-bit-per-pixel image of the polygon before
expanding it to the screen.
The area used for the workspace may be allocated from offscreen memory
(a description of which is returned by the geCoffscreen_memory function)
or from from heap using gsp_malJoc. It must be large enough to hold a
1-bit-per-pixel representation of the current screen coordinates with a power of 2 pitch.
Example
3-174
See fill_polygon.
TlGA Application Interface
Draw Styled Line
Syntax
Type
void styled_line (xl,
sho:r't xl, yl;
short x2, y2;
long style;
short mode
styled_line
yl, x2, y2, style, mode)
/* start coordinates
/* end coordinates
/* 32-bit line style pattern
/* selects 1 of 4 drawing modes
*/
*/
*/
*/
Extended
Description The styled_line function uses Bresenham's algorithm to draw a styled line
from point (xl, yl) to point (x2, y2). The line is a single pixel thick and is
drawn in the specified line-style pattern.
Q
Arguments xl and yl specify the starting coordinates.
Q
Arguments x2 and y2 specify the ending coordinates.
Q The last two arguments, style and mode, specify the line style and
drawing mode.
Argument style is a long integer containing a 32-bit repeating line-style pattern. Pattern bits are used in the order 0,1, ... ,31, where 0 is the rightmost
bit (the LSB). The pattern is repeated modulo 32 as the line is drawn. A bit
value of 1 in the pattern specifies that the foreground color is used to draw
the corresponding pixel. A value of 0 in one of the line style pattern bits
means that the corresponding pixel is either drawn in background color
(modes 1 and 3) or not drawn (modes 0 and 2). Four drawing modes are
supported:
mode 0
Do not draw background pixels (leave gaps), and do
load new line-style pattern from style argument.
mode 1
Draw background pixels in COLORO, and load new linstyle pattern from style argument.
mode 2
Do not draw background pixels (leave gaps), and do reuse old line-style pattern (ignore style argument).
mode 3
Draw background pixels in COLORO and re-use old linestyle pattern (ignore style argument).
The current style pattern used by the styled_line function is available by
calling the gecenv function. See the gecenv function description for more
information.
3-175
styled_line Draw Styled Line
Example
#include
#include
#include
CONFIG config;
main ()
{
long xl, yl, x2, y2, i, mask;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
/* draw spiral using styled line segments
set_draw_origin(config.mode.disp_hres»l,
config.mode.disp_vres»l);
x2 = 0;
y2 = -20 « 16;
/* line style pattern
mask = Ox93E493E4;
styled_line (0, 0, 0, 0, mask, 0);
for (i = 1500; i > 0; --i)
*/
*/
{
xl
x2;
yl
y2;
x2 += yl » 4;
y2
xl» 4;
styled_line (xl»16, yl»16, x2»16, y2»16,
-1,2);
set_videomode(PREVIOUS, INIT);
3-176
T1GA Application Interface
Swap Source and Destination Bitmaps
Syntax
void swap_bm()
Type
Extended
swap bm
Description The swap_bm function swaps the pointers to the structures containing
the source and destination bitmaps. This is useful for copying bitmap data
offscreen, then at some later point, swapping the bitmaps and restoring
the data back onscreen.
Example
See zoom3ect.
3-177
synchronize Synchronize Host and GSP Communications
Syntax
void synchronize ()
Type
Core
Description The synchronize function ensures that the TMS340 completes all pending
operations before it returns. TIGA supports two-processor execution and
some conditions require them to be synchronized. For instance, if the host
downloads data that is being manipulated by the TMS340, it is essential that
the TMS340 finishes with it before the host overwrites the data.
Example
3-178
See instalLusererror.
TlGA Application Interface
Render an ASCII String
Syntax
int text_out (x, y, pSt ring)
short x, y;
unsigned char far *pString;
Type
Core
text out
Description The texeout function renders the ASCII string pointed to bYpString in the
currently selected font using the current set of text drawing attributes. The
string is a null terminated sequence of 8-bit ASCII character codes.
The starting position of the string is specified by arguments, x and y. Coordinate x is the position at the left edge of the string, and coordinate y is the
position at either the top of the string, or the baseline, depending on the text
alignment attribute set by a call to set_textattr.
The return value is the x coordinate of the next character position to the right
of the string. If the string lies entirely above or below the clipping rectangle,
the unmodified starting x coordinate is returned.
3-179
text width
Return Width of an ASCII String
Syntax
int text_width(pString)
unsigned char far *pString;
Type
Extended
Description The text_width returns the width of the string in pixels, as if it were rendered
using the current selected font and the current set of text drawing attributes.
3-180
T/GA Application Interface
Transparency Off transp_ off
Syntax
void transp_off ()
Type
Core
Description The transp_off function disables transparency for subsequent drawing op-
erations. The transparency mode set by default is mode 2, transparency on
result equals zero (see seCtransp function}.That is, if the pixel operation
involving source and destination pixels is 0, the destination pixel is not altered. This can be modified forTMS34020 systems by using the seCtransp
function.
Example
See seCdstbm.
3-181
transp_on Transparency On
Syntax
void transp_on ()
Type
Core
Description The transp_on function enables transparency for subsequent drawing op-
erations. The transparency mode set by default is mode 2, transparency on
result equals zero (see seCtransp function).That is, if the pixel operation
involving source and destination pixels is 0, the destination pixel is not altered. This can be modified forTMS34020 systems by using the seCtransp
function.
Example
3-182
See call to transp_off in seCdstbm.
T1GA Application Interface
Wait for Scan Line
waiCscan
Syntax
void wait_scan (line)
short line;
/* wait until this scan line is reached */
Type
Core
Description The waiCscan function waits for a scan line on the CRT to be refreshed.
This function does not return control to the calling routine until the specified
line is scanned by the electron beam. Control is returned at the start of the
horizontal blanking interval that follows the designated line. Scan lines are
numbered in ascending order, starting with line 0 at the top of the screen.
Only visible scan lines are counted.
This function can be used to synchronize drawing operations to the electron
beam of a CRT display. For example, when drawing an animated sequence
of frames, transitions from one frame to the next appear smoother if an area
of the screen is not redrawn at the same time it is output to the CRT.
If argument line is less than 0, the function uses the value 0 in place of the
argument value. If argument line is greater than the bottom scan line, the
function uses the number of the bottom scan line in place of the argument
value.
3-183
zoom reet
Zoom Rectangle
Syntax
void zooffi_rect(ws,
short ws, hs;
short xs, ys;
short wd, hd
short xd, yd;
short linebuf;
Type
hs, xs, ys, wd, hd, xd, yd, linebuf)
/* source width and height
/* source top left corner
/* destination width and height
/* destination top left corner
/* scan line buffer
*/
*/
*/
*/
*/
Extended
Description The zoom_rect function expands or shrinks a source rectangle on the
screen or a linear bitmap to fit the dimensions of a destination rectangle on
the screen. Horizontal zooming is accomplished by replicating or deleting
rows of pixels. This type of function is sometimes referred to as a stretch blit.
The first four arguments define the source rectangle:
(JI The width ws
(JI The height hs
(JI The coordinates of the top left corner (xs, ys)
ws and hs must be non-negative.
The next four arguments define the destination rectangle:
(JI Width wd
(JI Height hd
(JI Coordinates of the top left corner of the rectangle (xd, yd)
wd and hd must be non-negative.
The final argument, linebuf, is a buffer large enough to contain one complete line of the display. The function uses the buffer as temporary working
storage; The minimum buffer size (in bits) is the number of pixels per line
times the number of bits per pixel. This buffer is a pointer to TMS340
memory and therefore must be allocated (by calling for example gsp_malloc) before invoking the function.
The zoom_rect function can be made to zoom from a linear bitmap by setting the source bitmap global using the seLsrcbm function. This function
only works if the pixel size of the source bitmap is the same as the screen.
Thus, if the desired effect is to perform a zoom3ect on binary data, this
must be done in two stages. First download the binary bitmap and use bitblt
to expand this to the current pixel size to a linear bitmap. Then perform a
zoom3ect on this linear bitmap onto the screen.
3-184
TlGA Application Interface
Zoom Rectangle
Example
zoom reet
#include
#include
#include
CONFIG config;
short far arrow_shape[] =
Ox0003, Ox0007, OxOOOF, Ox001F, Ox003F, Ox007F, OxOOFF,
Ox01FF, Ox03FF, Ox01FF, Ox007F, OxOOF7, OxOOF2, Ox01EO,
Ox01EO, OxOOCO
};
#define
#define
ARROW W
ARROW H
16
16
main()
{
int i;
PTR arrow_addr_bin, arrow_addr_col, buffer;
long arrow_size;
if (set_videomode(TIGA, INIT I CLR_SCREEN»
{
if (install-primitives() >= 0)
{
get_config(&config);
/* set up linear bitmap with binary data for arrow */
arrow_size = ARROW_W * ARROW_H;
arrow_addr_bin = gsp_malloc«arrow_size+7)/8);
/* transfer shape data from host to gsp
*/
host2gsp(arrow_shape, arrow_addr_bin,
(arrow_size+7)/8,0);
/* set up a color bitmap for the arrow shape
*/
arrow_size *= config.mode.disp-psize;
arrow_addr_col = gsp_malloc «arrow_size+7)/8);
/* set the source bitmap to the binary arrow shape */
set_srcbm(arrow_addr_bin, ARROW_W, ARROW_W,
ARROW_H,l);
/* set destination bitmap to the color arrow shape */
set_dstbm(arrow_addr_col, ARROW W *
config.mode.disp-psize, ARROW_W, ARROW_H,
config.mode.disp-psize );
/* blit binary arrow and expand it to color arrow
*/
set_colors(LIGHT_CYAN, LIGHT_BLUE);
bitblt(ARROW_W, ARROW_H, 0, 0, 0, 0);
3-185
zoom_rect Zoom Rectangle
/* set the source bitmap to the color arrow
swap_bm();
/* set the destination bitmap to the screen
set_dstbm(Ol, 0, 0, 0, 0);
/* set pixel processing to max as the results are
/* normally better
setypop(20);
/* set up zoom-rect buffer to hold 1 scan-line
buffer = gsp_malloc(config.mode.disp_hres *
config.mode.dispysize);
/* now zoom-rect the arrow to the screen
zoom_rect(ARROW_W, ARROW_H, 0, 0, ARROW_W«2,
ARROW_H, 0, 0, buffer);
*/
*/
*/
*/
*/
*/
set_videomode(PREVIOUS, INIT);
3-186
TIGA Application Interface
Dynamic Load Module
4.1
Dynamic Load Module
The key to TIGA's extensibility is the Dynamic Load Module (DLM). This
module is a collection of C or assembly routines written by the application
or device driver programmer, and linked together to form the module. The
DLM is downloaded at run time into TMS340 memory and integrated with
the TIGA graphics manager. Once downloaded, each routine contained
within the module is callable using the same conventions as the TIGA core
or extended primitives.
TIGA currently supports two types of dynamic load modules:
I:l Relocatable load module (RLM), and
I:l Absolute load module (ALM).
The routines which compose a dynamic load module can be either standard C-type functions callable from either the host processor or from the
TMS340, or interrupt service routines called on reception of an interrupt via
the TIGA standard interrupt handler.
4.1.1
Relocatable Load Modules
Relocatable Load Modules (RLMs) are produced directly using the TMS340
compiler and assembly tools and are in common object file format, or COFF.
A description of this file format is given in the TMS34010 Assembly Language Tools User Guide. These modules contain the necessary relocation
entries so that they can be loaded anywhere in TMS340 memory. They may
also contain unresolved references to TIGA core or extended primitives,
which are resolved when they are loaded. Furthermore, they contain all the
necessary symbol information stored after loading a symbol table file so that
subsequent RLMs that are loaded may reference the functions in another
RLM. The installation of an RLM is performed by invoking the install_rim
function which, in turn, invokes TIGALNK, the linking loader.
4.1.2
Absolute Load Modules
Absolute Load Modules (ALMs) are created from relocatable load modules
by calling the create_aim function. This function in turn calls the linking
loader to link and save (instead of link and load) the resultant TMS340
memory image. TIGALNK uses the TIGA heap management routines to allocate a space in TMS340 memory where the ALM will be loaded. TIGALNK
then links and relocates the module to the area starting address in heap.
Thus, the ALM can only be loaded into this one area in memory. The heap
area for the module is then freed by the create_aim routine. It is therefore
imperative that the state of the heap in TMS340 memory is the same when
the ALM is created as when it is installed. Normally, this can be achieved
4-2
Extensibility Through the User Library
Dynamic Load Module
by always initializing heap prior to calling create_aim and then reinitializing
heap when the module is installed. Heap initialization can be performed by
calling secvideomode with an INIT style.
The reason for incorporating ALMs into TIGA is that installation of RLMs
requires the application or device driver written for TIGA to call the
install31m function, which in turn invokes the linking loader. This requires
about 70 -1 OOK bytes of free main host memory, depending on the symbol
table size of the module being installed. For many applications this is the
most direct and flexible method for installation of functions, as the module
can be relocated and the symbols accessed by subsequent module loads.
However, for certain applications and application drivers, not enough
memory is available to use this method. An example of this is the AutoCAD
driver, ADI. By the time AutoCAD calls the ADI, all available PC memory
has been appropriated, leaving no room for install_rim to invoke the linking
loader. Using the ALM, no memory is required. The install_aim function
contains only a short piece of code to load the module into TIGA, since no
external linking or relocation needs to be made. The create_aim function
can be called when ADI is installed (at boot time). Because this is prior to
AutoCAD being invoked, the PC memory is free to invoke TIGALNK to create
the ALM file.
When loading an ALM, heap is allocated to store the moQule. The start address is compared to the one returned when the module was created. If they
are the same ,the ALM is loaded into TIGA; if not, the load is aborted. A
further restriction with ALMs is, since the symbol information is also no longer available within the file (as it is with RLMs), that modules loaded subsequently cannot reference functions in an ALM.
4-3
Generating a Dynamic Load Module
4.2
Generating a Dynamic Load Module
A TIGA dynamic load module consists of the following three parts:
[J
a
[J
A collection of C and/or assembly routines, some (or all) of which are
to become TIGA extensions or interrupt service routines.
TIGAEXT section declaration. Required only if TIGA extensions are being declared.
TIGAISR section declaration. Required only if TIGA interrupt service
routines are being declared.
This document does not describe the mechanics of generating the TMS340
source and object code of a user function. This is discussed fully in the
TMS34010 C Compiler Reference Guide and the TMS34010 Assembly
Language Tools User's Guide. If the user library is to contain functions written using TMS3401 0 assembly code then certain guidelines need to be met
to ensure that the C environment is maintained by the assembly language
function. For a description of how to interface assembly language routines
with the C environment, see Section 5.4 of the TMS34010 C Compiler Reference Guide.
Dependent on whether or not a DLM contains extensions or interrupt services routines, one or two specially named COFF sections must be created
and linked with the module. If the module contains extensions, the a section
called TIGAEXT must be created. If the module contains interrupt service
routines, then a section called TIGAISR must be created. The format of
these sections is described below.
4.2.1
TIGAEXT Section
The TIGAEXT must contain one and only one address reference for each
extension contained within the module (that is callable from the host). For
example, if the module contains two functions called my_funcl and
my_func2 the section declared would look like this:
;-_._-------------------------------------------------------;
;TIGAEXT - This COFF section contains references for all
;extensions contained in the module it is linked with.
i----------------------------------------------------------;
;External References
.globl my funcl, my func2
;Start section declaration
. sect ". TIGAEXT"
.long
my funcl command number 0 within module
.long -my-func2 command number 1 within module
• text
- end section
4-4
Extensibility Through the User Library
Generating a Dynamic Load Module
'*
...
~:"~f~:::::::::
4.2.2
~.
The TIGAISR Section
The TIGAISR section contains two entries for every interrupt service routine
contained within the module. These entries specify an address reference
to the ISR and the interrupt number of the ISR.
For example, if two ISRs called my_intl and mLintlO were contained
within the module, then the section declared would look like this:
,------------------------------------------------------ ------,
;TIGAISR - This COFF section contains information for all
of the ISRs contained in the module it is l'inked with.
;
;
i----------------------------------------------------------j
;External References
.globl
my intl,
my intlO
; Start secfion declaration
. sect
" . TIGAISR"
.long
my intl
.long
1 ;interrupt number 1;
. long
my int10
.long
10 ;interrupt number 10;
. text
; end section
Note that the TIGAEXT and TIGAISR sections must contain the exact number of declarations for the external functions to be installed. This is because
TIGALNK uses the length ofthese sections to determine the number of declarations.
4.2.3
Linking the Code and Special Sections into an RLM
Once the user functions have been written, they are compiled and/or assembled, producing a series of COFF object files (. obj). These files should
be partially linked together with the object files generated by assembling
the TIGAEXT and/or TIGAISR sections. Below is an example where two
functions and two interrupt service routines are created and linked into a
RLM.
The source files contain the following:
myfuncs
tigaext. asm
myints. asm
tigaisr. asm
Functions my_funcl and my_func2
References for the above (as in the example)
Two interrupt routines, my_intl, and my_intlO
References and Trap numbers for the above ISRs
Step1: Assemble and/or compile all of the source files:
cc myfuncs tigaext myints tigaisr ~
This produces four object files:
myfuncs.obj
tigaext.obj
myints.obj
tigaisr.obj
4-5
Generating a Dynamic Load Module
Step 2: Partially link all the object modules together to form the RLM:
gsplnk -0 EXAMPLE.RLM -r -cr myfuncs.obj tigaext.obj
myints.obj tigaisr.obj ~
The result of the linking is a relocatable load module entitled EXAMPLE. RLM.
Note:
In some versions of the linker, the warning: -Unresolved Reference to
"_c_initOO". is displayed. It can be ignored.
4-6
Extensibility Through the User Library
Installing a Dynamic Load Module
4.3
Installing a Dynamic Load Module
To invoke the commands installed in a dynamic load module, it must first be
installed into the TIGA graphics manager. The module file is in the form of
a file in a directory of the host PC. If this directory is not the current working
directory, the TIGA environment variable must first be set up to point to this
directory. TIGALNK uses the environment variable to find the DLM. The actual installation procedure differs from RLM to ALM.
4.3.1
Installing a Relocatable Load Module
A relocatable load module is installed by the install_rim function. Below
is an example program written in Microsoft C which explains how to install
the example described in the previous section, EXAMPLE. RLM.
Example 4-1.
#include
maine)
{
short module;
/* initialize TIGA */
if (!set_videomode(TIGA, INIT»
{
printf("Fatal Error - TIGA not installed\n");
exiteD);
}
/* attempt to install module */
if «module = install_rlm("EXAMPLE"»
< 0 )
{
printf("Fatal Error - couldn't install Example RLM\n");
printf("Error code = %d\n", module);
exit(O);
/* code to invoke the module functions */'
set_videomode(PREVIOUS, INIT);
The install_rim function is invoked with the filename of the RLM file. Either
a full path name can be given, or just the final part of the filename, when either the current directory is used or that directory set by the TIGA environment variable. A default extension of . RLM is assumed unless one is given.
The install_rim function will return either the module id for the RLM, which
will be used when the functions are invoked, or an error code if some error
occurred. Error codes are negative values, module identifiers are always
positive (including zero).
4-7
Installing a Dynamic Load Module
~~..:::;~..m:;'';:;::~::::::&"-:"':;::~Z%::mss:;:;::~:;:::;:::;:::::;~''::::~~h:;<7hX'"h~W''''/UH..:¥h::e:Z~%:;::::·;:;'';:''''';:m.
~;::~~Jl'X::::
4.3.2
....................z.w~-:;:~:;:;:;:;::w~~;::::;;:::;:;~.:::;:;:l'/..x:;:;:;:;:::w-/;:;Z9.'
Installing an Absolute Load Module
An absolute load module must first be created from a relocatable load module. Below is an example program written in Microsoft C that explains how
to create an ALM from the example described in the previous section.
Example 4-2.
#include
main{)
(
register return_code;
if{!set videomode{TIGA, INIT»
(
printf{"Fatal Error, TIGA interface not installed.\n");
exit (l);
}
1*
attempt to create the module *1
return code = create alm ("EXAMPLE", "EXAMPLE");
if (return code < 0)(
printf{"Fatal Error in creation of 'alm' file\n");
printf{"Error code = %d\n", return_code);
exit{l);
}
1*
*1
further initialization code
set_videomode{PREVIOUS, INIT);
in it driver ()
(
register return_code;
if{!set videomode{TIGA, INIT»
(
printf{"Fatal Error, TIGA interface not
installed.\n");
return{O);
}
1*
attempt to install the module
return code = install alm{"EXAMPLE");
if (return code < 0) {
printf ("Fatal Error in installation of ' alm' file \n") ;
printf{"Error code = %d\n", return code);
return{O);
-
*1
}
1*
code to invoke the module functions
*1
set_videomode{PREVIOUS, INIT);
4-8
Extensibility Through the User Library
Installing a Dynamic Load Module
~S1*~wmr*
:~
'mso::::::;
The example assumes that at the time the program is run initially, TIGALNK
can be invoked by create_aim to produce the ALM file. The invocation produces an EXAMPLE. ALM file in the same directory as EXAMPLE. RLM. Default
extensions of .RLM and .ALM are assumed unless overridden by the file
names supplied. create_aim produces an ALM file only if it does not already exist. This generally saves the program the unnecessary time of recreating the ALM every time the program is run. If the application requires
to create a new ALM, it must first delete the old one explicitly.
The example also assumes that the part of the program that uses the user
extensions in the ALM is performed after invoking the iniCdriver function.
This scenario is typical with application drivers. The main program actually
does very little more than initialization and calling the DOS TSR exit function. Later, the application calls an iniCdriver type function to get the driver
ready for subsequent application calls. At this time the TIGA environment
is re-initialized and the ALM is installed. install_aim does not invoke
TIGALNK but uses a trivial loader to move code from the host PC file into
TMS340 memory.
4-9
Invoking Functions in a Dynamic Load Module
4.4
Invoking Functions in a Dynamic Load Module
The process of invoking a function in a DLM is done in two parts. The first
part involves the selection of the function, which is described in this section.
The second part is the actual invocation of the function and the passing of
its parameters from the host to the TMS340. That part is described in subsequent sections.
4.4.1
Command Number Format
User extensions that are installed in a DLM are identified by a unique command number. This command number consists of a 16-bit word split into the
following fields, as Figure 4-1 shows:
Figure 4-1. Command Number Format
16 14 13 12
1 :
1 :
'--____
V
functlcn
type
11 10
9
:
:1
:
V
8
7
:
6
:
A
module
number
6
:
4
:
3
:
2
:
1
:
0
:
V
I
,
function
number
1) The function type (Bits 14-15) :
00 = direct-mode
01 = C-packet
10 = reserved for future use
11 = reserved for future use
2} The module number (between 0 and 31) (Bits 9 - 13) :
31 for TIGA core primitives.
30 for TIGA extended primitives installed via the install_primitives
function.
othru 29 for user modules in the order of installation.
3) The function number within the module (Bits 0 - 8).
The function type field currently selects between the C-packet mode and direct-mode functions. These two modes determine the manner in which the
parameters of the function are passed between the host and the TMS340.
The two modes will be described in subsequent sections.
The module number is a unique identifier for each module. TIGA supports
up to 32 DLMs, numbered from 0 to 31. The TIGA core primitives are always
installed at initialization time as module number 31. Likewise, the DLM that
4-10
Extensibility Through the User Library
Invoking Functions in
a Dynamic Load Module
contains the TIGA extended primitives is always assigned module number
30 by the install...,primitives function. The remaining 30 module slots, numbered 0-29, are assigned to user DLMs as they are installed. The first user
DLM installed is assigned the number 0, the second the number 1, and so
on.
The function number specifies one of the 512 possible functions that can be
contained within a module. Function numbers are defined by the order that
they are declared in the TIGAEXT section within a module. Forthe example,
described in Section 4.3 mLfunc1 would be designated function number
0, and mL func2 would be designated function number 1.
4.4.2
Using Macros in Command Number Definitions
The definition of the command number may be subject to change in future
versions of TIGA. To minimize the potential changes to an application, macros are provided in the TIGA. H include files to enable the command number
of a function to be specified without referencing the individual bits in the
command number. These are the macros:
CORE CP(function number)
CORE-OM (function-number)
EXT CP(function number)
EXT-OM (function-number)
uSER CP(module T function number)
USER=OM(module I function=number)
cORE_cpandcoRE_oMselectC-packetordirect-modefunctionswithamodule
numberof31 (for the TIGAcore primitives). Similarly, EXT_CP and EXT_oMselect C-packet or direct-mode functions with a module number of 30 (for the
TIGA extended primitives). USER_CP and USER_OM are used for user extensions. They take a single argument, which is the module number returned
by the install_rim or install_aim function ORed with the function number
ofthe function from its position in the TIGAEXT section. The module number
should be passed as it is supplied from the install procedure.
These macros should always be used when specifying command numbers.
Ifthey are not, and an application hard-codes the bits in acommand number,
there is a risk of incompatibility with future versions of TIGA.
4-11
Invoking Functions in a Dynamic Load Module
4.4.3
Passing Parameters to the TIGA Function
The invocation of a TIGA function can be done in two ways, depending on
the type of function call that is made. These are C-packet or direct-mode
calls.
C-packet functions are the easiest of the two to write and have a more flexible parameter format. C-packet functions receive their parameters on the
stack; thus it is very easy to develop a function that becomes a user extension by first writing it and debugging it on the host side. The function can then
be extracted from the host code and be recompiled under the TMS340 C
compiler. Any parameters it received on the host side will be passed from
host to TMS340 via a TIGA communication driver routine and then pushed
onto the TMS340 C stack so that the function behaves just as if it were invoked local to the host. To do this, however, extra data must be sent along
to the TMS340 describing the type and size of each parameter.
The extra overhead of sending this data, plus the time taken to format the
parameters and push them onto the stack can be eliminated by using direct-mode. This just sends raw data into the communication buffer used for
host to TMS340 communication. The user extension function receives on
the stack a single parameter that is a pointer to the communication buffer
where the data is stored. The function itself must pick up the data from this
buffer in the expected format.
Most applications will be developed using C-packet initially. Those functions
that are more time critical would be modified to use direct-mode. The
changes to the source code of an extension to change it from C-packet to
direct-mode are not that significant as will be seen from examples given later. The following sections give a complete description of C-packet and direct
modes.
4-12
Extensibility Through the User Library
C-Packet Mode
4.5
C-Packet Mode
To invoke a User extension using C-packet mode, three pieces of information need to be supplied:
[J
The type of call the function uses
[J The function's command number
[J
4.5.1
Description of the function arguments
The Type of Call
The current C-packet system supports three basic types of function calls:
cp_cmd
This entry point is for functions that do not require any form
of return data.
This entry point is for functions that require only a single standard C type return value.
This entry point is for those functions which pass pointers to
data that is modified indirectly by the function called.
draw_a_line(xl, yl, x2, y2)
poly line(lO, &point list)
i = ~ead-point(x, y)copy_mem( &src, &dst, len)
would
would
would
would
use
use
use
use
cp_cmd
cp_cmd
cp_ret
cp_alt
An additional set of entry points is used when the argument list has the potential of being too large for the size of the communication buffer used to
transfer parameters between the host and the TMS340. These entry points,
cp_cmd_a, cp_reCa, and cp_aICa, have the same functionality as those
described above, with the added capability of allocating additional space for
large amounts of arguments data, at a cost of speed performance. These
entry points should be avoided when the user knows that the argument
length of the function in question will not exceed the maximum size dictated
by the communication buffer's data size (which is a field of the CONFIG
structure returned by geCconfig).
4.5.2
The Command Number
Section 4.4.1 on page 4-1 0 describes in detail the command numberformat.
The command number should always be specified in the form:
USER_CP (module I function_number)
for user C-packet extensions, where module is the module ID of the DLM
returned at install time and funct ion_number is the position of the function
in the TIGAEXT section.
4-13
C-Packet Mode
4.5.3
Description of Function Arguments
To call the desired function, each of that function's arguments must be understood by the graphics manager, so data can be passed to the DLM function in the expected form. Each individual argument is called a packet and
has its own separate header. Entering the packet headers is made easier
by the use of additional defines in the TIGA. H include file to represent the
different data types. Below is a list of the currently supported data types:
_WORD (a)
_SWORD (a)
_DWORD(a)
_BYTE_PTR(b,a)
_WORD_PTR(b,a)
_DWORD_PTR(b,a)
_STRING (a)
_ALTBYTE_PTR(b,a)
_ALTWORD_PTR(b,a)
_ALTDWORD_PTR(b,a)
Immediate WORD argument a
Immediate signed WORD argument a
Immediate Double WORD argument a
BYTE array ptr a with b elements
WORD array ptr a with b elements
DWORD array ptr a with b elements
Null-terminated string ptr a
Function altered BYTE array pointer
Function altered WORD array pointer
Function altered DWORD array pointer
Because the immediate arguments passed in Microsoft C are always promoted to short type, there is no BYTE identifier. If immediate char values
are passed, either the_woRD or _SWORD identifier should be used. Also, since
immediate short types are the only data types that need be promoted (to 32
bits) by the graphics manager, they are the only data size to have a signed
identifier. All other arguments' sign extension requirements should be handled by the called routines.
4.5.4
C-Packet Examples
The exact argument list of the C-packet entry points is as follows:
entry-point_name(CMD_ID, num-packets, packetl,
... , packetn)
where:
cm number
npackets
packetl ... packetn
command number
number of C type packets
Packet data (see below)
Below are some examples of user extensions. These examples are not
supplied TI-extended primitives.
4-14
Extensibility Through the User Library
C-Packet Mode
Example function:
Q The function requires no return data. (Use cp_cmd)
Q
Q
The function's command number was stored in CMD ID.
The function has no arguments.
Resulting include file entry:
Example function:
fill_rect(w, h, x, y)
Q
The function requires no return data. (Use cp_cmd.)
Q The function's command number was stored in
Q The function has 4 arguments, all WORDS.
CMD ID.
Resulting include file entry:
*define fill rect(w,h,x,y)
\
cp_cmd(USElR_CP(CMD_ID),4,_WORD(w),_WORD(h),_WORD(x),_WORD(y»
Example function:
poly_line(n, &linelist)
Q
Q
Q
The function requires no return data (Use cp_cmd.)
The function's command number was stored in CMD ID.
The function has 2 arguments, WORD, nand WORD_PTR, line list.
Resulting include file entry:
*define poly line(n,ptr)
\
cp_cmd(USElR_CP(CMD_ID),2,_WORD(n),_WORD_PTR(2*n,ptr»
4-15
C-Packet Mode
Example function:
init_matrix(&matrix)
[l The function initializes the array pointed to by &matrix indirectly. (Use
cp_Blt)
The function's command number was stored in CMD ID.
Q The function has 1 argument which points to a 4 x 4 element function
altered array of longs.
Q
Resulting include file entry:
#define init matrix(ptr)
\
cp_alt(USER_CP(CMD_ID),l,_ALTDWORD_PTR(16,ptr»
4.5.5
Overflow of the Command Buffer
When a command of any kind (primitive or user function) is invoked by an
application, the communication driver functions transfer its parameters from
host memory into a temporary buffer in the TMS340 memory (called a command buffer). If one of the parameters of the function is a pointer, then the
pointer itself is not copied over, only the data that is being pointed to is copied. If the pointer is an array, as in the polyline function, then it can be of
arbitrary length. Thus, it is very simple for the application to overflow this
fixed length buffer by, for example, asking TIGA to draw a million element
polyline. The application must know the size of data that it is attempting to
transfer into the TMS340 processor memory and check that it will fit in the
command buffer. For this reason, the command buffer size is included as
an element in the configuration structure returned by geCconfig. Note that
if a C-packet entry point is being used, allowances must be made for the
packet type and size words, which also use space in the command buffer.
Memory space management is required for all direct-mode and three regular C-packet entry points. However, the application can use the _B C-packet
entry points (for example, cp_cmd_B) which check the size of the parameters and download them in the normal way if they fit. If they do not fit, the
entry points attempt to allocate a temporary buffer from the heap pool to
store the parameters. If the allocation is not successful the error function is
invoked. The checking of the parameter size requires two passes through
the arguments and thus some speed overhead is incurred using this technique. However, a rapid real-time function does not commonly use arrays
too large to tit in the command buffer.
4-16
Extensibility Through the User Library
C-Packet Mode
Another technique provided in TIGA for the management of large amounts
of data, which may overflow the command buffer, is the direct-mode entry
pOints dm-poly and dm_ipoly. These entry points turn the buffer into a circular queue so that any size of data can download into the buffer. This technique requires the writing of a custom TMS340 processor command that
manages the data and the handshaking employed.
4-17
Direct Mode
4.6
Direct Mode
The principal difference between C-packet and direct modes is that in direct
mode,when the downloaded function is invoked on the TMS340 side, the
arguments are not on the stack as in C-packet mode. The downloaded function is invoked with a single argument, which is a pointer to a data area
where the host downloaded the parameters. The function itself must fetch
them from this data area into the local variables.This process makes the
writing of functions slightly more complicated, but this is offset by the increase in performance. These functions are intended to improve the performance of invoking TIGA extensions from TMS340. They are not meant
(although they could be used) for functions that are called from other downloaded functions from the TMS340 side. Such functions that need to be
called from both the host and TMS340 (by another downloaded function)
are best written in C-packet or should have an alternate C-callable entry
point.
Note that for the fastest possible transfer of data the direct mode entry
points do not check the size of the data being transferred. The application
has to ensure that the data being transferred does not overflow the command buffer.
A further difference between C-packet and direct mode was that in C-packet
mode the arguments passed to a function could be of any combination of
immediate data and pointers in any particular order. This is not the case with
direct-mode. No packet information is sent with the data, specifying whether
it is immediate or not, and its size. It is the direct-mode entry point itself that
determines what format the parameters can be specified in, and, in turn,
how these parameters are received in the TMS340 communication buffer.
In the following sections is a list ofthe direct-mode entry points and the parameterization of their arguments.
4.6.1
Standard Command Entry Point
void dm cmd(cmd number, length, argl, .. ,argn);
short- cmd nuni'ber;
short length;
short argl •.• argn;
This command is the most commonly used for direct-mode commands in
the TIGA system. It has a single length argument and an arbitrary-length
list of immediate value arguments; it has no return value. The length specified is the number of 16-bit words that are sent; thus to send a long, length
should increase by 2.
4-18
Extensibility Through the User Library
Direct Mode
The TIGA core function poke_breg uses this entry point. It sends a 16-bit
register number and a 32-bit value to be loaded into the register. Note that
the length is three, since three16-bit words are pushed onto the stack (2 of
them being the MSW and LSW of value).
#define poke breg(regno,value)
\
dm_cmd(POKE_BREG,3, (short) (regno), (long) (value))
The data in the communication buffer looks as follows:
Figure 4-2. Data Structure of dm_cmd
data_ptr
-
16-blt words
regno
value (LSW)
value (MSW)
The poke_breg function has one parameter on the stack, which is
dataytr. The function contains the following TMS340 assembly code to
extract the data from the communication buffer:
_dmyoke_breg:
move
AO, *-SP, 1
move
setf
move
move
*-A14,A8,1
16,1,0
*AB+,AO,O
*AB,A8,1
save AO
(Field Size 1 is 32-bits by default)
get dataytr
set Field Size 0 to 16-bits
get regno into AD
get value into AB
4-19
Direct Mode
4.6.2
Standard Command Entry Point with Return
unsigned
short
short
short
long dm ret (cmd number, length, argl,
cmd number;
length;
argl ••• argn;
.•• , argn);
This command is similar to dm_cmd described in Section 4.6.1 on page
4-18. The difference is that after calling the TMS340 function, the host waits
for the command to finish, and then fetches and returns the standard C return value. The value is returned as a long, but is of the same type as that
returned by the called routine (signed or unsigned, etc.). The value is returned in the DX:AX registers. As with dm_cmd, dmJet specifies length
in 16-bit words.
The TIGA core primitive get_nearesCcolor uses this entry point. It sends
4 bytes of red, green, blue, and intensity (which are all promoted to shorts
by the C-compiler), returning a long index into the palette.
dm_ret(GET_NEAREST_COLOR, 4,
4-20
(short) (r), (short) (g)
(short) (b), (short) (i) )
Extensibility Through the User Library
Direct Mode
4.6.3
Standard Memory Send Command Entry Point
void dm-psnd(cmd_number, length, ptr)
short
cmd number;
short
length;
char far
*ptr;
This command is used to call functions that require information in the form
of an array or structure. Note that in this case the length specified is in bytes,
not 16-bit words as in the previous two entry points. The ptr argument is
a far pointer into host memory. The contents of this pointer are down loaded
into the communication buffer.
The TIGA extended primitive draw_polyline uses this entry point. Notice
that the numpts is multiplied by 4 since every point consists of two coordinates (x and y), each of which is 2 bytes long.
*define draw-polyline(numpts,pts)
dm-psnd(DRAW_POLYLINE, (short) (4*(numpts)),
(short far *) (pts))
\
\
The data in the communication buffer looks as follows:
Figure 4-3. Data Structure of dm_psnd
dat&.-ptr
-
16-blt words
numpts x 4
ptslOJ.x
x coordinate of first point
ptslOJ.y
y coordinate of first point
ptsl1J.x
x coordinate of second point
ptsl11.y
y coordinate of second point
4-21
Direct Mode
Because the entry point always sends the byte count into the first word of
the communication buffer, the TMS340 function itself must scale it to a
point-count by dividing the value by 4. The primitive contains the following
TMS340 assembly code to extract the data from the communication buffer:
_dm_draw-polyline:
4-22
move
setf
move
*-A14,A11,l
16,1,0
*A11+,A10,O
srI
2,A10
get data-ptr
set field Size 0 to 16-bits
1st word is number of bytes
the post-increment of All means that
it is now a pointer to pts[O]
convert to numpts
Extensibility Through the User Library
Direct Mode
4.6.4
Standard Memory Return Command Entry Point
unsigned long dm-pget(cmd_number, length, ptr)
short
cmd number;
short
length;
char far
*ptr i
This command is used to call functions that return information in the form
of an array or structure. The length (in BYTES) is sent as the first element
in the command buffer and invokes the TMS340 function. The function
writes the return data into the communication buffer at the word following
the length.
The TIGA core primitive get...,palet uses this entry point. Notice that the
nument parameter is multiplied by 4 since each palet entry consists of a red,
green, blue, and intensity byte.
#define get-palet(nument,pal)
\
dm-pget(GET_PALET, (short) (4*(nument», (char far *) (pal»
The data in the communication buffer contains the one word of data before
the function is invoked:
Figure 4-4. Data Structure Before Invoking dm...,pget
16-blt words
data..ptr----1--t1
nument _ 4
I
Following the invocation of the buffer the communication buffer contains:
Figure 4-5. Data Structure After Invoking dm...,pget
data..ptr
-
16-blt word
nument • 4
paIlO).g : paIlO).r
red and green values of first entry
paIlO).1 : paIlO).b
blue and Intensity of first entry
4-23
Direct Mode
4.6.5
Standard String Entry Point
void dm-pstr(cmd_number, ptr)
short
cmd number;
char far
*ptr;
This command is similar to dm-psnd, but instead of sending a pointer with
a known length, it sends a null-terminated string. In this case, the communication buffer has no length entry as the first word. Successive bytes of the
buffer contain the characters in ptr with a null (zero) terminator.
An example for this entry point can be found in the communication entry
points tests in the TIGA release (in directory tigapgms\tests\coms).
4.6.6
Altered Memory Return Command Entry Point
unsigned long dm-palt(cmd_number, length, ptr)
short
cmd number;
short
length;
char far
*ptr;
This command is used to send and return information in the form of an array
or structure. This entry point combines the functionality of the dm-psnd
and dm_pget entry points to send the contents of a pointer (of length bytes), which is then modified by the TMS340 function. When it completes the
data is returned back into the host memory pointed to by ptr.
An example for this entry point can be found in the communication entry
points tests in the TIGA release (in directory tigapgms\tests\coms).
4.6.7
Send/Return Memory Command Entry Point
unsigned long dm-ptrx(cmd_number, send_length, send-ptr,
return_length, return-ptr)
short
cmd number;
short
send length;
char far
*send-ptr;
short
return length;
char far
*return-ptr;
This command is used to send information in an array or structure and return
information to a different array or structure. It is similarto dm-palt in Section
4.6.6 except that data is returned to a different area of host memory.
An example for this entry point can be found in the communication entry
points tests in the TIGA release (in directory tigapgms\tests\coms).
4-24
Extensibility Through the User Library
Direct Mode
4.6.8
Mixed Immediate and Pointer Command Entry Point
void dm-pcmd(cmd_number, num_words, wordl, word2, ... ,
num-ptrs, cntl, ptrl, cnt2, ptr2, ... )
short
cmd number; /* command number
num-words;
/* number-of words to send
short
wordl;
/* immediate data
short
short
word2;
short
short
char far
short
char far
num-ptrs;
cntl;
*ptrl;
cnt2;
*ptr2;
*/
*/
*/
/* number of pointers to send
/* number of bytes in pointer 1
/* pointer data
*/
*/
*/
This command combines immediate and pointer data. The first parameter
after the command number is the number of words {num_words} to send in
the same manner as dm_cmd. Following that are the words themselves
on the stack. After the immediate data is a count of the number of pointers
to send {num-ptrs}. Each pointer is preceded by a count of the number of
bytes contained in the array or structure that the painter is pointing to.
An example for this entry point can be found in the communication entry
points tests in the TIGA release {in directory tigapgms\tests\coms}.
4.6.9
Mixed Immediate and Pointer Command Entry Point with Return
unsigned long dm-pret(cmd_number, num_words, wordl, word, .. ,
num-ptrs, cntl, ptrl, cnt2, ptr2, .. )
short
/* command number
cmd numbers;
num-words;
/* number-of words to send
short
short
wordl;
/* immediate data
word2;
short
short
short
char far
short
char far
num-ptrs;
cntl;
*ptrl;
cnt2;
*ptr2;
/* number of pointers to send
/* number of bytes in pointer 1
/* pointer data
*/
*/
*/
*/
*/
*/
The command dm_pret is similar to dm-pcmd except that it returns a standard C value in the DX:AX registers.
An example for this entry point can be found in the communication entry
paints tests in the TIGA release {in directory tigapgms\tests\coms}.
4-25
Direct Mode
4.6.10 Poly Function Command
void dm-po1y(cmd_number, packet_number, packet_size, packet-ptr)
short
cmd number;
short
packet number;
short
packet-size;
char far *packet-ptr
This entry point is different from every other C-packet and direct-mode entry
point in that it does not simply transfer data from host to TMS340 memory
and invoke a command. This command is used for operations that require
a large amount of data to be transferred and when a certain degree of parallelism is possible; that is, some of the data being sent can be processed
while the rest is beingsentdown. Forexample, theADI redraw function used
by the TIGA AutoCAD driver uses this entry point to draw some vectors
while others are being sent by the host.
The command buffer used by the communication driverto download the parameters is turned into a circular queue of packets. The command buffer
contains the following:
Figure 4-6. Data Structure of dm_poly
16-bit words
dataJ)t~
total number of packets
number of packets in a burst
packets sent
packets used
start of packet 1
I
This entry point sends a burst of packets down from the host to the TMS340.
It updates the packets-sent count and monitors the packets-used count to
ensure thatthere is enough room to download more packets. The userfunction must be specially written to comprehend this handshaking scheme and
be responsible for the update of the packets used entry.
4-26
Extensibility Through the User Library
Direct Mode
Example 4-3.
i----------------------------------------------------- ----------
TIGA - Graphics Manager function
;--------------------------------------------------------------; Usage: Example GSP shell routine with dm-poly entry point.
i----------------------------------------------------- ---------Include GSP register definitions
. copy
gspregs.inc
Include macros
.mlib
gspmac.lib
Declare globals
.globl
example dmpoly
External References; Arguments Received from Host
aTOTAL .set
0
;total number of packets
aPAGE
.set
10h
;packets per page
aSENT
.set
20h
;packets sent
aUSED
.set
30h
;packets used
aDATA
.set
40h
;data starts here; Register usage
Rarg
.set
AO
;pointer to arguments
Rccurrent
.set
A1
;count (current)
Rctotal
.set
A2
;count (total packets)
Rctemp
. set
A3
; count (temp)
Rcpage
.set
A4
;count (total per page)
Rdata
.set
A5
;pointer to data
BURST SIZE
.set
16
example dmpoly:
mmtm
SP,AO,A1,A2,A3,A4,A5,A6,A7,A9
Popc
Rarg
;get pointer to args
move
*Rarg(aTOTAL),Rctotal,O ;get total packets
move
*Rarg(aPAGE),Rcpage,O
;get packets per page
clr
Rccurrent
;clear current count
page_loop:
move
Rarg,Rdata
addi
aDATA,Rdata
Push
Rcpage
burst loop:
- movk
BURST SIZE,Rctemp
;Rctemp is number pkts
sub
Rctemp,Rctota1
jrge
full burst
add
Rctotal,Rctemp
clr
Rctotal
full burst:
add
Rctemp,Rccurrent
;current count up to date
check_loop:
move
*Rarg(aSENT),AS,O
Get count ready
sub
Rccurrent,AS
Sub off desired count
jrlt
check_loop
If not ready, then wait
4-27
Direct Mode
packet_loop:
i--------------------------------------------------------------Grab some data and do something with it
;--------------------------------------------------------------move
*Rdata+,A6,1
move
move
*Rdata+,A7,1
*Rdata+,A9,O
dsjs
move
move
jrz
subk
jrgt
Pop
jruc
Pop
mmfm
rets
Rctemp,packet loop
Rccurrent,*Rarg(aUSED),O
Rctotal,Rctotal
exit
BURST SIZE,Rcpage
burst-loop
Rcpage
page loop
Rcpage
SP,AO,Al,A2,A3,A4,A5,A6,A7,A9
2
i---------------------------------------------------------------i
exit:
4.6.11 Immediate and Poly Data Entry Point
void dm ipoly(cmd number, nShorts, sData, ... , ItemSz,
nfiems, pData)
unsigned short cmd number;
/* command number
*/
unsigned short nShorts;
/* Number of immediate short
words to send
*/
unsigned short sData;
/* First short word of data
to send
*/
unsigned short ItemSz;
unsigned short nItems;
char far *pData;
/* Size of items that follow
(in bytes)
*/
/* # of items that follow */
/* Pointer to data to send */
This entry point is similar to dm_poly; it is used for operations that require
a large amount of data items to be transferred, and the TMS340 has the ability to operate on 1 or more data items at a time. Some of the data can be
processed by the TMS340 while more is being sent down.
A user function located on the TMS340, which expects data sent by this
entry point, must be coded using a specific set of rules. When the TMS340
function is called, it will receive a data pointer in TMS340 memory. The data
at that address will consist of the immediate data values. The poly data that
is sent in bursts by the host requires special processing and communication
protocol in orderto be received. In orderto isolate this from the userfunction,
a service routine is provided called srv_ipoly. This service routine should
be called, once the user function is ready to process the poly data. The parameters for this function are as follows:
srv ipoly(pItemSrv, pDataBuf)
VOid (*pItemSrv) (); /* Ptr to item handler
char *pDataBuf;
/* Address after last immed. word
*/
*/
The pDataBuf argument is the address immediately following the last immediate word received by the user function.
4-28
Extensibility Through the User Library
Direct Mode
The pItemSrv is the address of a function that can, in turn, be called by
srv_ipoly to handle 1 or more Items. This function will be called repetitively
by srv_ipoly until all the items have been received by the host and serviced.
This function will be called with the following arguments:
(*pltemSrv) ( nltems, pltems);
unsigned short nltems;
/* Number of items this time
char *pltems;
/* Pointer to data
*/
*/
The nItems argument is the number of items requiring service. The pItems
argument is the address of a data buffer containing nItems worth of data.
The following is an example of how this entry point can be used. Forthis example, a polypixel command is implemented. The function has 2 immediate
arguments, the foregound color of the pixel, and the raster op to be used to
draw the pixels. The remaining poly data is an array of points where pixels
are to be drawn.
The host program to call the entry point would look like this:
dm_ipoly(CMD, 2, color, rop, 4, nPoints, pData)
where:
CMD
Command number of the polypixel function.
2
Specifies that two immediate arguments follow: color and rop.
color
First immediate argument.
rop
Second immediate value.
4
Each item is a point, which in this case is two words. The first
specifies the X coordinate, the second specifies the Y. The size
of the item is therefore 4 bytes.
nPoints
Specifies the number.
pData
Pointer in host memory where the point resides.
4-29
Direct Mode
The downloaded TMS340 user function called polypixellooks like this:
,---------------------------------------------------------TIGA - POLYPIXEL - Example User function
;---------------------------------------------------------Example of a downloaded GSP function which uses the
dm_ipoly host entry point.
,-----------------------------------------------------------Include GSP register definitions
. copy
gspregs.inc
Include macros
.mlib
gspmac.lib
Declare globals
.globl
PolyPixel
External References
.globl
srv ipoly
Polypixel argument definition
aCOLOR .set
0
aROP
.set
10h
aDATA
.set
20h
address passed to srv_ipoly
-
4-30
PolyPixel:
mmtm
SP,AO,Al,A2
setf
16,0,0
move
@CONTROL,A2,0
;save CONTROL register
Popc
AO
;get pointer to data
move
*AO(aCOLOR),Al,O ;get color
move
Al,COLORl
;set gsp foreground color
move
*AO(aROP),Al,O
; get raster op
setf
5,0,0
move
Al,@CONTROL+10,0 ;use it to set gsp pp op
setf
16,0,0
Ready for poly data, push the address following the
immediate data and the address of the service routine
Push
STK
move
AO,A8
addi
aDATA, A8
Pushc A8
;push data address
movi
drawpixels,A8
Pushc A8
;push item service routine
calla
srv ipoly
All done, cleanup and exit
move
A2,@CONTROL,0
;restore CONTROL register
mmfm
SP,AO,Al,A2
rets 2
Extensibility Through the User Library
Direct Mode
,----------------------------------------------------------Item service routine: drawpixels
This function is called repetitively by the srv ipoly
function until all the items sent by the host have been
received and serviced. This function is called with two
stack parameters, the 1st parameter is the number of
items requiring service, and the 2nd argument is the
address of the data items in 340 memory.
,
e __________________________________________________________ _
drawpixels:
mmtm
SP,B10,B11,B12,B13
move
STK, B13
move
*-B13,B10,1
move
*-B13,B11,1
move
B13, STK
drawloop:
addk
1, COLOR1
move
*B11+,B12,1
pixt
COLOR1,*B12.XY
dsjs
B10,drawloop
mmfm
SP,B10,B11,B12,B13
rets
2
;save registers
;pop number of items
;pop ptr to item data
;get Y:X pixel coords
;draw a pixel
;loop until items exhausted
;restore registers
4-31
Downloaded Function
4.7
Downloaded Function
User extended routines and interrupt service routines contained in a dynamic load module have the ability to access functions or globals which were
previously installed into TIGA. This includes the core primitives and the TI
extended primitives (provided that they have been installed by the application). Note that certain primitives are host-only primitives and cannot be
invoked by a dynamically loaded routine. These are
create_aim
create_esym
field_extract
field_insert
flush_esym
flush_extended
geCisr_priorities
geCmodeinfo
geCvideomode
gsp2host
gsp2hostxy
host2gsp
host2gspxy
install_aim
install_primitives
install_rim
install_usererror
seCconfig
seCtimeout
seCvideomode
synchronize
The downloaded function, whether written in TMS340-C or assembly language, can take advantage of all the facilities of the graphics manager, specifically it can
4-32
1)
Invoke nearly all the TMS340 primitive functions as if they were written
on the host side. Thus, it can invoke the function setj)alet with the
parameters used in Microsoft C. Not all the primitives can be invoked
from the TMS340 side since some require access to host side data
structures, such as those concerned with the linking loader. Two include files containing the graphics manager core functions and extended functions (gsptiga. hand gspextnd. h) are supplied for this purpose. This capability has the advantage that an application can be written and debugged on the host side using Microsoft debug tools and
then individual functions can be downloaded onto the TMS340 side with
no changes.
2)
Access global variables of the graphics manager, such as those specifying display coordinates, directly without invoking functions to do it. An
include file containing the graphics manager global variables
(gspglobs . h) is supplied for this purpose. The file is shown in the figure below, which details the global variables thatthe downloaded extension is free to access in the current version of TIGA.
Extensibility Through the User Library
Downloaded Function
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
extern
long bottom of stack;
CONFIG config; PALET DEFAULT PALET[16];
CURSOR DefaultCursor;
long end of dram;
ENVIRONMENT-env;
ENVCURS envcurs;
ENVTEXT envtext;
MODE INFO *modeinfo;
MONITORINFO *monitorinfo;
MODULE Module[32];
OFF SCREEN AREA *offscreen;
PAGE *page;
PALET palet[];
PATTERN pattern;
char *setup;
short sin tbl[];
long stack size;
long start-of dram;
FONT sysfont;PACKET *sys free;
long *sys_memory;
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
declared in link file
current configuration
default palette
default cursor struct
declared in link file
environment variables
cursor environment
text environment
operating mode info
monitor timing info
function module descr.
pointer to current data
pointer to current data
current palette in use
current pattern info.
current setup pointer
sine look-up table
declared in link file
declared in link file
system font
pointer to free packets
pointer to heap packets
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
*1
Where these variables reference a specific type of declaration, such as
the include file gsptypes . h should also be included to define this type
of declaration.
PALET I
4.7.1
Register Usage Conventions
Assembly language functions used in conjunction with the TIGA primitives
should follow certain guidelines for register use. The following registers
must be restored to their original states (the state before the function was
called) before control is returned to the calling routine:
[,l Status register fields FE1 and FS1 must be restored. Fields FEO and
FSO need not be restored.
[,l All A-file registers except A8 must be restored. A14 should not be used
as a temporary variable by a user function. It must always contain a
pointer into the C parameter stack, because an interrupt service routine
(ISR) may interrupt a user function, and that ISR may call a C function
using the C stack.
[,l
In general, all B-file registers must be restored. However, certain B-file
registers may be altered by attribute control functions that update parameters such as COLORa and COLOR1.
[,l
In general, I/O registers CONTROL, DPYCTL, CONVDP, and INTENB
should be restored before returning to the calling routine. However,
some I/O register bits may be altered by attribute control functions that
update parameters such as the plane mask, pixel processing operation,
or transparency flag. These register bits typically are not changed by
graphics output functions.
4-33
Downloaded Function
Upon entry to a downloaded extension, certain registers are in a known
state and contain well-defined parameters. These assumptions cannot be
made
of interrupt service
routines, since they
can interrupt a function
that
_____ 1_____
J: .a.L _ _ _ _ _ _
-I!.t.t: _ _ _ _
r- ...... __ -.: __ _
! _ _.
____
U~ U~lIlg UII~
IIlay
UI
!_.l. ___
LlI~~~ l~gl~L~I~
~
___
lUI a
.I.
_
•• _ _ _ _ _
UIII~I~IIL (JUI(JU~~.
t:}\'L~II~IUII~,
however, can assume that the following registers are in these states:
l:i Status register:
•
•
•
FE1 = 0
FS1 = 32
FEO and FSO are undefined
l:i A-File Registers: STK - A 14 points to the C-parameter stack.
l:i B-file registers:
DPTCH
Screen pitch (difference in starting memory addresses of
any two successive scan lines in display memory).
OFFSET
Memory address of pixel at top left of screen.
WSTART
Top left corner of current window.
WEND
Bottom right corner of current window.
COLORO
Source background color.
COLOR1
Source foreground color.
l:i I/O registers:
4-34
CONTROL
Contains current pixel processing operation code and
transparency control bit. These are set by the application
program and may vary from one call to the next. In contrast, in the window mode, PBH and PBV bits are set to
specific values. The window mode is set to enable clipping without interrupts (W = 3). The PBH and PBV bits are
both zero.
CONVDP
Is set up for the screen pitch.
PMASK
Contains the current plane mask.
Extensibility Through the User Library
Downloaded Function
4.7.2
TIGA Graphics Manager System Parameters
The TIGA graphics manager assumes that certain system parameters are
under its control. Dynamic load modules should not alter the following registers:
The master interrupt enable bit (IE) in the status register.
The cache disable bit (CD) in the CONTROL register.
The DRAM refresh control bits (RR and RM) in the CONTROL register.
Q The four host interface registers (HSTADRL, HSTADRH, HSTDATA,
and HSTCTL).
Q
Q
Q
4-35
Example Programs
4.8
Example Programs
The TIGAPGMS directory that is shipped with TIGA contains several exampie functions. To gain the maximum benefit from the foliowing sections of
this guide, they should be read in conjunction with a hard copy of the listings
of the source code of those examples.
4.8.1
Stars Example
The TIGA release disk with the example programs contains a stars directory
that is an example of the use of C-packet and direct-mode extensions of
TIGA. This demonstration program may be familiar because it has been
ported to many different graphics environments. It basically consists of moving through a three-dimensional galaxy in which stars grow larger as they
are approached and then disappear off the edge of the screen. As they do
so, new stars are created in the distance. This scenario is performed in four
ways. First, using host calls to TIGA extended primitives to perform the
drawing of the stars. Second,where the host calls to a custom TMS340 C
routine using the C-packet communication mechanism. Third, where the
host calls a custom direct-mode C routine. Finally, where the direct-mode
routine has been re-written using TMS340 assembly code. The stars program prints out the elapsed time to call these different functions, and the
time saving is evident. It should be noted at the outset that this example,
though demonstrating the capabilities of downloading TIGA extensions, is
very artificial. The time savings in a real application is typically better than
with this example, especially when the downloaded function performs
something a little more substantial than drawing a few pixel-wide stars.
This example consists of the following source files:
stars. c
Main program (Microsoft-C)
star.h
Insert file containing type definitions and external references
data.c
Star shapes
starscp. c
C-packet extension to draw a star (TMS340-C)
starsdm. c
Direct-mode extension to draw a star (TMS340-C)
starsasm. asm Direct-mode extension to draw a star (TMS340-assembly)
starsgsp. asm TIGAEXT file describing extension routine names
4-36
Extensibility Through the User Library
Example Programs
The routine that forms the downloaded extension is one that draws a single
star. The four versions of it are
draw- star- host in file stars. c
draw_star_cp
in file starscp.c
draw star dm
in file starsdm. c
draw- star- asm
in file starsasm. asm
Acomparison between the draw_star_host and draw_star_cpshows that
besides the function name, the two are identical (apart also from the more
important fact that one is compiled in Microsoft C and the other in TMS340
C). This underlines an important advantage of TIGA: that it is possible to
take an existing application running under Microsoft C, move a function to
the TMS340 side, and invoke it with the same parameterization as if it were
locally resident and obtain an immediate speed improvement, as can be
seen from running this program. Furtherspeed improvement can be accomplished with just a little more work.
A comparison between the draw_star_cp and draw_star_dm functions
shows that after the first four lines of the direct-mode version, the functions
are again identical. The only difference between them highlights the fundamental difference between C-packet and direct-mode functions. Directmode functions receive parameters, just as the host downloads them, as
sequential items in a communication buffer. The direct-mode function receives a single parameter, which is a pointer to the data area of the communication buffer where the data has to be fetched. In the C-packet case, the
functions parameters are sent down in packets describing the size and type
of the data being sent. Then a C-packet interpreter parses these packets
and pushes parameters onto the stack where the C-packet extension expects to find them. This enables the C-packet routine to be called just as if
it were local to the host program, but it incurs the additional time overhead
of sending more information in the packet than the data itself.The direct-mode extension eliminates this overhead but puts a very slight extra
burden on the extension to fetch its own data. Because the transition from
C-packet to direct mode is very simple, it is expected that most applications
will use C-packet to start and then move to direct mode forthose time-critical
functions that need to be optimized.
The final function draw_star_asm also uses direct mode, but the function
no longer uses the TIGA bitblt function to draw the star. Instead, it re-codes
the whole function in TMS340 assembly language. This function requires
the most effort form the application programmer to produce. Not every extension should use this approach, but there is a well-defined route that allows an easy progression from host alone, through the simpler approaches
4-37
Example Programs
of C-packet and direct mode, to the custom assembly function. The custom
assembly function allows a programmerto develop applications quickly, optimizing time-critical functions to the limit.
4.8.1.1
Generating the Downloadable Extension File
The extension consists of the files containing the three downloaded subroutines, a data file containing the star shapes, and a special file containing the
TIGAEXT section {starsgsp}. The latter declares the list of downloaded
functions to be installed in a specific order so that they can be referenced
later. The order in which the functions appear in the TIGAEXT section define
the command numbers used when the functions get invoked thus:
draw_star_cp has a command number of 0, draw_star_dm. has a command number of 1, and draw_star_ asm has a command number of 2. All
these files are linked together using the TMS340 linker {in the make file} with
the -cr and -r options.This produces the relocatable load module
starsgsp. r1m. Note that in building the rim file the linker produces the message » warning: entry point symbol_c_intOO undefined. This can be
ignored.
4.8.1.2 Installing the Downloadable Extension File
The initialization routine of stars. c performs the installation of the rim file
by calling install_rim. If the call to installJlm returns a negative result, an
error occured; if it returns a positive number or zero, it is the module number
of the installed group of functions. Every installed RLM receives its own
module id. The first id is 0, the second id is1 , etc. Because this application
was invoked with seCvideomodestyle of INIT, which initializes the heap,
aRd as a by-product of this, deletes all extended primitives that were installed, the application can be assured that the id of the first set of installed
extensions is o. Thus, the module identifier {mod_star} can be a constant
o in the program.
The expected approach for the common mode of operation is that an application flushes out all extended primitives and downloads a single RLM file
containing all its extensions. This approach has some minor speed improvements over the more general approach where the module number is not
known until runtime and the command number needs to be stored in a variable.
Note that no directory is specified in the filename of the downloadable extension. This is not a problem for a development environment because the
current directory is the one searched first and the one where the extension
is stored. In a production mode where different TIGA applications and drivers are stored in different directories, the user should set up a TIGA library
directory that is pointed to by the -1 field of the TIGA environment variable.
4-38
Extensibility Through the User Library
Example Programs
4.8.1.3
Invoking the Downloadable Extensions
The three update_cp, _drn and _asm functions are the ones that actually
need to invoke the extensions. The extensions are invoked through the use
of TIGA communication entry points; cp_cmd for the C-packet call and
drn_ cmd for the two direct-mode calls. To make the invocations more readable, these calls are #defined to function calls that look like regular host
functions.
All the communication entry points take as a first parameter the command
number of the TMS340 function to be invoked. The entry point consists of
a function command number indicating the order in which the function appears in the TIGAEXT section, ORed with the module number (which from
the previous section is known to be 0 and so can be ignored). Following that
are the commands parameters:
1) C-Packet The number of PACKETS, 4, followed by 4 WORD packets
with parameters of the actual parameter data. The WORD macros build
a packet containing the data size and type for the C-packet handler to
interpret.
2) Direct Mode The number of 16-bit words, 4, followed by four 16-bit
words pushed onto the stack.
4-39
Example Programs
4.8.2 Curves Example Program
The curves example program draws a series of graphs of mathematical
f.
1+ it" ,.,i""";J .......... " +h_ "'... _ ..__ ,, ___ 1_ ...J ___ ... : ..... _...J _ ..... _ •• _ T .... _ _ ,....: __ .-I:"
,,,""L'U""" 'L '''' "'""",;., LV .,11::; ;;)LClI;;) I:1i\ClIIIIJII:1 UI:1;;)\'IIUI:IU Cl.UVVI:I. 1111:1 IIIClJVI UII""'Mi"n~
ference is that it installs the extensions as separate modules. Thus, rather
than assuming the module id is 0, the module id that is returned from the
3 calls to install_rim, is stored in the global variables module_draw_cp,
_dm, _fp.
The downloadable extensions are all passed an array of (x,y) coordinates
which they draw. The points are produced by a generate.:....curve function,
which involves a series of calls to a runtime support math function involving
floating point arithmetic. The final list of pOints are, for the C-packet and direct-mode calls scaled, to screen coordinates.
The _ fp case is a bit different. It passes a list of floating point values which
are scaled to the screen by the extension function. It illustrates how floating
point values can be passed through TIGA. Currently TIGA does not support
the passing of floating point parameters directly. The reason is not due to
TIGA but to the fact that TMS340 floating point numbers are not in IEEE format (and require conversion to and from IEEE format). The floating point extension contains the source code of IEEE format conversion routines, which
can be used for this. The TMS340 floating point format will be available in
IEEE format in the near future, and direct floating point support will then be
put into TIGA.
4.8.2.1
Speed Optimization of Parallel Processing
The timing of the extensions is done in two ways: First, time is taken directly
following the functions being invoked (without synchronization). This gives
a much shorter time than the second set of timings, which are taken after
a call to the synchronize function. In the first case the time measured is that
taken by the host. Second is the time taken by both the host and the
TMS340. The TMS340 is a coprocessor and can offload much of the graphical processing from the host and do it much faster. However, the time saved
by an application also depends on utilizing both processes in parallel. If the
application is written so that the host is simply waiting for the TMS340 to
complete, then little or no time may be saved.
When the application can perform an operation, say the calculation of the
next set of graphical drawing coordinates, while the TMS340 is drawing, is
whent the best performance improvements are achieved. This is important
when choosing the communication entry points to use. Entry points that return values, such as cPJet, cp_alt, dm_ret, dmJ)trx, etc. all cause the
host to wait until the TMS340 is finished. If a downloadable extension, which
takes a long time to execute, is to return status information, it is perhaps bet4-40
Extensibility Through the User Library
Example Programs
ter to split the function into two. One to do the drawing, the other to return
the status. That way the host calling function can invoke the first function
without waiting, then go on to perform some calculations that are not dependent upon the status, then call the status function some time later. This utilizes both processors more efficiently.
4.8.2.2 Invoking Downloadable Extensions
The invocation of the three downloadable extensions brings out some further points that were not covered by the stars example. Referring to the #defines for the communication entry points:
IJi C Packet: This illustrates the passing of pointers in C-packet mode. Notice that the third parameter c is also used to determine the size of the
second parameter b. This is a very typical case. Unless a pointer is
pointing to a fixed size structure, a parameter is needed to tell the calling
function how big the array being passed really is. This parameter can
be used to tell the communication driver how much to send. The value
may require scaling, as in this case, c refers to the number of vertices
being passed, but as each vertex is made up of two 16-bit coordinates
(x, y), the number of WORDS to be sent is c*2.
IJi Direct Mode:The direct-mode entry point dm-pcmd allows the transfer of combinations of immediate data and pointers. The parameters
are:
- 1
- a
- 1
- c*4
-
b
number of immediate words being sent
immediate word
number of pointers being sent
number of BYTES to be sent in the pointer
(far) pointer to the data
Note that the c parameter is not sent explicitly as an immediate word.
This is because since it is used as a count for the pointer data b, it appears in the communication buffer multiplied by 4. Because the downloaded extension can recreate it by a simple shift there is no point in
sending it down twice. Notice too that the size is sent in BYTES not WORDS
as it is for C-packet. What ends up in the communication buffer is best
seen by consulting the routine draw_curve_dm.
IJi Floating Point: Although the floating point uses a DOUBLE_PTR
which looks as a TIGA macro, it is defined in the curves program. TIGA
treats doubles (which are the only floating point parameters passed to
routines, floats are always promoted to doubles) as an array of 4 unsigned 16-bit words. Consult the function draw_curve_fp to see how
the conversion of floating point occurs. Although this example does not
show it, the ALTDOUBLE_PTR can return floating point values from TIGA
4-41
extensions. These floating point values require reconverting back into
IEEE format using gsp2ieee.
4-42
Extensibility Through the User Library
Example Programs
4.8.3
ADI Driver Example
The ADI directory contains the source of an example driver for ADI release
3.1 which works with AutoCAD release 9. There is no discussion on how to
write an ADI driver, since this is fully covered in the ADI Driver Development
Kit that can be obtained from AutoDESK Corp. The only details given here
are regarding certain features of TIGA utilized in this driver.
4.8.3.1
Installing an ALM
The requirement for an AlM has been fully discussed in Section 4.1.2 . The
main program (in file adi . c) makes a call to create_aim to create the AlM
from the RlM that is shipped with the driver. Then a trial call to install_aim
is made, to see if there will be any problems in installing the AlM (for example, not enough heap) later. Toward the end of the main program, a call is
made to the initialize function in the adiasm.asm file, to turn the program
into a terminate-and-stay-resident task. Note that previously a call is made
to seCvideomode{PREVIOUS, to end the TIGA session and return the
board to an IBM graphics mode, such as EGA.
later, when AutoCAD is invoked and a drawing is edited, AutoCAD makes
a call to the pini t function (in adi. c). The pini t function calls
seCvideomode{TJGA, to start the TIGA environment and then calls
install_aim to install the AlM.
4.8.3.2 Linking the Extended Primitives with the User RLM
There is no call to install.j)rimitives in the ADI driver; although, some of
the extended primitives are used in the driver. These primitives are linked
in with the ADI driver primitives and are loaded simultaneously. Thus, in the
adiext . asm file, references are made to TIGA extended functions such as
draw_line, bitblt, etc. These primitives are supplied in TIGA both as an
RlM and in the form of a library that can be linked. This library is referenced
when the ADI RlM is created (see adiext. cmd).
The advantage of linking the extended primitives with a user load module
is that only those functions that are needed by the application are included,
freeing up valuable space in TMS340 memory. Also, the time to load the
functions is reduced. However, since the extended primitives are being
loaded into a user module, their command numbers need to be modified.
This is why their definitions appear in a header file adiext . h and why the
TIGA extended primitive definitions appear in a separate include file extend. h rather than in tiga . h. This enables their command numbers to be
changed without the need to edit the standard TIGA include files.
4-43
Installing Interrupts
4.9
Installing Interrupts
Interrupt service routines contained within a dynamic load module must be
written as a function called with no arguments; that is, the last instruction
should be a RETS 0 instead of a RETI. This is because the TIGA graphics
manager provides a general interrupt handler that invokes the interrupt routines only ifthey are enabled. This handler performs the actual RETI instruction to return from the interrupt.
In addition, the handler also provides for chaining of multiple interrupt service routines on a single interrupt level. This is vital for the TMS340 processor, which often has more than one display interrupt active. For instance,
the graphics manager provides three interrupts to control a hardware emulated cursor, page flipping, and wait-scan, all using the display interrupt.
The interrupt service routines must be installed into the general interrupt
handler during the installation of a dynamic load module.The routines that
are to become interrupt service routines must be written, compiled, and assembled. A specially named TIGAISR section mustthen be declared, identifying the name of each interrupt service routine and the level where it should
be installed. The format of this section is explained in Section 4.2.2 on page
4-5. During the download process, the information within this special section is used to chain interrupts into the TIGA interrupt handler, where each
interrupt is assigned a priority level. The interrupt priority can be retrieved
for each ISR declared in the TIGAISR section, after a successful installation,
by performing a call to geCisr_priorities. This routine returns an interrupt
priority for each ISR in their order of declaration in the section. Each interrupt
is also installed in a disabled state and must be explicitly enabled by the programmer.
The seCinterrupt function must be called to enable or disable a particular
interrupt service routine. The interrupt level and the associated priority must
be specified as arguments to this function.
Note that it is possible for a downloaded extension to be executed from the
host and, in turn, set the traps to its own server to avoid the overhead of the
global interrupt handler in certain time-critical functions. However, care
must be taken, especially in the display interrupt used by TIGA primitives
such as the cursor functions. If equivalent support is not given to these functions, as provided by the global interrupt handler, certain TIGA primitives
may not execute correctly.
Certain TMS340 boards provide external connection to the LlNT1 and
LlNT2 TMS340 processor pins. In such cases, interrupt service routines
can be written for them using the techniques outlined here. However, such
techniques are clearly not portable across all TMS340 processor boards.
4-44
Extensibility Through the User Library
Installing Interrupts
4.9.1
Clock Example of Using Interrupts
This example displays a real-time analog clock on the TMS340 screen,
which is updated by the use of the timer interrupt function installed in the display interrupt.
The timer functions are trivial, as can be seen in the timer .asm file; they
simply increase a count. There is an additional function get_time, which
returns the value of the count to the host. Notice that the TIGAEXT section
is included with the timer. Because this is an assembly language program,
there is no need to keep TIGAEXT separate. There is an additional TIGAISR
section, that is similar to TIGAEXT but holds an interrupt level in addition.
The installation of the interrupt service routine (ISR) is exactly the same as
for a regular extension, except that directly after the call to install_rim is a
call to get_isr_priorities (see main program of clock. c). These calls return the priority value for each of the interrupt service routines installed. Note
that this means that an array big enough to hold all these priorities must be
declared prior to invoking geCisr-priorities to hold the values that will be
returned. In this example only one ISR is installed, so a single short variable
will suffice. The priority is used in the call to seCinterrupt to enable the interrupt. It is required, since TIGA allows any number of ISRs on a given interrupt level; thus the priority is the mechanism for identifying individual
ISRs.
Following the call to geCisr-priorities is a call to seCinterrupt. This takes
two parameters to identify the ISR (an interrupt level and a priority) and two
parameters, which may be set; an enable/disable flag and a display line (the
latter is valid only for display interrupts and is ignored by interrupts at other
levels).
After the interrupt is enabled, no direct reference is made to it. The function
geCtime is used to return the value of the count and thus determine the
elapsed time. The geCtime function in this example is not #defined; there
is no absolute requirement to do this, but it is also clear that the code is less
readable because of it.
4-45
Installing Interrupts
4.9.2
Ball Example Using Interrupts
This example demonstrates many oHhe same features of the previous example with one major exception. The interrupt service routine performs
some graphics operation (in the form of drawing a ball on the screen). Because the graphics operation uses implied operands in the B-file and I/O
registers that cannot be guaranteed to be correct (since the interrupted routine could be using the OFFSET or DPTCH B-file registers as temporaries).
the interrupt service routine has to set up these values. Because this involves over-writing their current values, they must first be saved somewhere. In this example they are saved in a global structure, by the routine
setuP--9sp_env.ln an actual application. the registers could be pushed onto
the stack using an MMTM instruction, if this function were recoded in
TMS340 assembly. The graphics registers are then initialized using the values from the global structures such as CONFIG. After the ISR has completed, the restore--9sp_env function is called to restore the register values
prior to returning to the interrupted function.
4-46
Extensibility Through the User Library
The TIGA Linking Loader
4.10 The TIGA Linking Loader
The TIGA linking loader TIGALNK is the mechanism by which extensibility
is made possible. It is a full TMS340 linker that provides the capability of resolving references to TIGA graphics manager (GM) functions. TIGALNK is
a full COFF loader which provides the capability of relocating object code
anywhere in TMS340 memory. It is fully portable, using the TIGA communication driver to interface to any TMS340 board that has TIGA ported to it.
TIGALNK has extensibility control built into it, so that it can read the TIGAEXT
and TIGAISR sections and inform the graphics manager of the user extensions that are to be installed.
The linking loader is invoked by several TIGA primitives for installing extensions into TIGA, and for performing various other tasks. Applications and
device drivers written for TIGA should restrict themselves to the TIGA primitives and never invoke the linking loader directly, as the linker is subject to
change in future revisions of TIGA, while the procedural interfaces will remain the same. A list of linking loader flags with their procedural equivalents
is given in the list below:
Option Files
t
-ca
-cs
-ec
-fs
RLMNAME, ALMNAME
COFFNAME
RLMNAME
SYMNAME
-la
-lr
-lx
ALMNAME
RLMNAME
COFFNAME
Description
Link, then create an ALM
Create external symbol table
Check the RLM for errors
Flush external symbol table
Load ALM into GM
Link, then load into GM
Load and execute COFF file
Equivalent Function
create_aim
create_esym
none
flush_esym
Install_aim t
install_rim
load_coff
/gsp_execute
TIGALNK can install an ALM. This is not done by the Install_aim function, but by a function
in the communication driver.
Below is a detailed description of the TIGALNK options. Note that these options can be placed anywhere on the command line; they do not have to be
placed before filename arguments.
In addition to the flags are a -q (quiet) option and a -v (verbose) option. If
no options are specified, then the linker assumes normal command line operation and all working messages and error messages are displayed normally. Selecting quiet mode operation suppresses all textual messages,
and only error codes are returned upon termination (this mode is used in the
procedural interface}. In verbose mode operation, the linker provides messages during every internal operation.
4-47
The TIGA Linking Loader
4.10.1 / ca - Create Absolute Load Module
This option creates an absolute load module (. ALM) from the specified reloeatable load module (. RLM). If the name of the output ALivi ilie is not specified on the command line, then the base name of the RLM file is used, but
with a forced file extension of . ALM. Also, if no path information is supplied
for the output file, then it is placed in the path specified by the -1 option of
the TIGA environment variable.
4.10.2 / cs - Create External Symbol Table
This option reads the symbolic information from the specified COFF file and
places it in TIGA3 4 0 • SYM, or ifthe optional command line argument was specified, in the Symbol filename supplied.
4.10.3 / ec - Error Check
This command line option can be used to check the integrity of an RLM prior
to installing it. The TIGA graphics manager does not have to be active in order for this option to work, but if it is, the largest amount of available heap
that can be used to load RLMs is also displayed.
Once executed, the / ec option scans the specified RLM and prints out the
numberof extensions or interrupt service routines contained within the module. If none are present, that is, no .TIGAEXT or .TIGAISR section is present, then a warning message is displayed. The amount of heap required to
load the module is then displayed, and if the graphics manager is active, the
largest available block of TMS340 heap is also displayed.
Ifthe module contains any unresolved references that would not be resolved
at load time, these are printed out. This allows the user to resolved symbol
references before actually attempting to download and install the file.
Note:
Only symbols contained in the TIGA external symbol file (TIGA340 • SYM) are
used to resolve symbol references. As supplied, or after creation by the /lx
or /cs option, this file contains only the symbols for TIGAGM. OUT, the TIGA
core primitives. If the module being checked contains references to other
modules, such as the TIGA extended primitives, then these must be loaded
prior to performing the check.
Example:
TlGALNK
ILX
ILR extprims
- load and execute TIGAGM.OUT
- load TIGA extended primitives
TlGALNK
lEe
- check integrity of user. r1m
TlGALNK
(EXTPRIMS • RLM)
4-48
user
Extensibility Through the User Library
The TIGA Linking Loader
4.10.4 / fs - Flush External Symbol Table
This option flushes all but the symbols related to TIGAGM. OUT from the external symbol table, TIGA340. SYM. As the symbols for each installed module
are deleted, a call to the TIGA graphics manager is also made to delete the
module from TMS340 memory.
4.10.5 /la - Load and Install an Absolute Load Module
This option loads and installs an ALM into the active TIGA graphics manager
running on the target such that functions contained in the module can be invoked from the host.
Note:
ALMs contain no symbolic information, so modules loaded after an ALM
cannot make references to symbols contained within an ALM.
4.10.6 /lr - Load and Install a Relocatable Load Module
This option loads and installs an RLM into the TIGA graphics manager so
that functions contained in the module can be invoked from the host.
Symbols contained in the module are added to TIGA340. SYM, the external
symbol table, so that they can be referenced by modules loaded afterwards.
4.10.7 /lx - Load and Execute aCOFF File I Execute TIGA GM
This option has the ability to perform two distinct functions, depending on
whether or not a GOFF file is specified as a command line argument. If a
GOFF file name is provided on the command line, then it is loaded and executed much like the stand-alone GOFF loader provided with the TI software development board.
If a GOFF file name is not provided, then it is assumed that the TIGA graphics manager is to be loaded and executed. In this case, two additional functions are performed after TIGAGM. OUT is loaded and executed. The TIGA external symbol file (TIGA340. SYM) is created, and the symbols contained in
TIGAGM. OUT are written to it. Once complete, a call to the TIGA communication driver function handshake is performed to initialize communications between the host and the TMS340.
4-49
4-50
Extensibility Through the User Library
Appendix A
TIGA Data Structures
m:m
Hiii
This appendix contains the data structures used in TIGA. They are defined
in the include file typedefs. h.
Section
Page
A.1
A.2
A.3
A.4
A.S
A.6
A.7
A.8
A.9
A.10
A.11
A-2
A-3
A-S
A-6
A-7
A-11
A-13
A-14
A-1S
A-16
A-17
Integral Data Types ....... . . . . . . . . . . . . . . . . . . . . . . . . ..
CON FIG Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
CURSOR Structure .................................
ENVIRONMENT Structure ...........................
FONTINFO Structure ................................
MODEINFO Structure ...............................
MONITORINFO Structure ............................
OFFSCREEN Structure ..............................
PAGE Structure ....................................
PALET Structure ...................................
PATTERN Structure .................................
The structure definitions supplied refer to the C syntax. In the assembly language equivalent file, typedefs. inc, the structure name precedes every
field name. Thus, the hot x field in the cursor structure becomes cursor hot x. This is because in the macro assembler all fields must be
unique. Note that this also applies to the TMS340 side equivalent file
gsptypes. inc. This file also has all type definitions in uppercase. The two
TMS340 side type definition files gsptypes. hand gsptypes. inc contain
additional type definitions internal to TIGA and are not generally of use to
the applications programmer.
A-1
Integral Data Types
A.1
Integral Data Types
The TIGA data structures use the following type definitions throughout:
typedef
typedef
typedef
typedef
typedef
A-2
unsigned
unsigned
unsigned
unsigned
uchar
char
short
long
long
far
uchar;
ushort;
ulong;
PTR;
*HPTR;
TIGA Data Structures
CONFIG Structure
A.2 CON FIG Structure
This structure contains the configuration information. Part of this structure
is the MODE INFO structure defined in Section A.6, which describes the
board configuration. If alternate configurations are available, they can be set
using seCconfig.
typedef struct
{
ushort
ulong
ulong
ulong
ushort
ushort
ulong
ulong
ulong
ulong
ulong
ulong
HPTR
PTR
MODE INFO
}CONFIG;
version number;
corom buff size;
sys flags;
device rev;
num modes;
current mode;
program-mem start;
program-mem-end;
display-mem-start;
display-mem-end;
stack size;shared mem size;
shared-host addr;
shared-gsp addr;
mode; -
The CON FIG structure consists of the following fields:
version number
TIGA revision number, assigned by Texas Instruments.
corom buff size
Size, in bytes, of the communications buffer; application needs to ensure that the data sent does not
overflow this buffer, for commands that do not check
the size of the downloaded data.
Bits 0 - 7 indicate FPUs (Floating Point Units) are
present to be compatible with the TMS34020 coprocessor ID codes. Bits 8 -15 are reserved.
device rev
This function invokes the TMS340's REV instruction
and returns its result here.
num modes
Number of extended modes, for boards that allow the
switching between different display setups.
current mode
Mode number corresponding to the current operating
mode.
progra~mem_start
Start address of program memory.
program_mem_end
End address of program memory.
display_mem_start Start address of display memory.
A-3
CONFIG Structure
A-4
display_mem_end
End address of display memory.
stack size
Default stack size; can be modified using gsp_minit.
share mem size
Size (in bytes) of shared memory that is available for
the application to use.
share_host_addr
If share_size is nonzero, it is the start address in
host memory of the shared memory; otherwise it is
undefined.
share_gsp_addr
If share_size is nonzero, it is the start address in
TMS340 memory of the shared memory; otherwise, it
is undefined.
TlGA Data Structures
CURSOR Structure
A.3 CURSOR Structure
This structure defines the cursor shape parameter for the seCcurs_shape
function.
typedef struct
{
short hot X;
short hotJ;
ushort width;
ushort height;
ushort pitch;
ulong color;
ushort mask rop;
ushort shape r~p;
PTR data;
}CURSOR;
This structure consists of the following fields:
hot
X
Offset x-coordinate added to the top left corner of the
cursor shape to define the pixel specified by the
seCcurs_xy.
Offset y-coordinate added to the top left corner of the
cursor shape to define the pixel specified by the
seCcurs_xy.
width
Width of the cursor shape in pixels.
height
Height of the cursor shape in pixels.
pitch
Linear difference in the addresses of successive
rows of the cursor shape (in bits).
color
Foreground color index with which the cursor is
drawn.
mask_r~p
Pixel processing operation used when applying the
mask data to the background. This is normally specified as AND.
Pixel processing operation used when drawing the
shape of the cursor onto the screen. This is normally
specified as OR or XOR.
'
data
Pointer to TMS340 memory containing two contiguous arrays of width by height.The first array is the
mask data with Os where the cursor is located and 1s
elsewhere. The second array is the shape data,
which has 1s where the cursor is located and Os elsewhere.
A-5
ENVIRONMENT Structure
A.4 ENVIRONMENT Structure
The ENVIRONMENT structure contains the TIGA drawing environment
global variables.
typedef struct
{
ulong xyorigin;
ulong pensize;
PTR patnaddr;
PTR srcbm;
PTR dstbm;
unsigned long stylemask;
}ENVIRONMENT;
The ENVIRONMENT structure consists of the following fields:
A-6
xyorigin
Current drawing origin in y::x format set by seCdraw_origin
pensize
Current pen size arranged in y::x format, set by set.J)ensize
patnaddr
TMS340 address of current pattern, set by set.J)atn
srcbm
TMS340 address of current source bitmap structure, set by
seCsrcbm
dstbm
TMS340 address of current destination bitmap structure, set
byseCdstbm
stylemask
Current line style mask used by styled_line function
TlGA Data Structures
FONTINFO Structure
A.5 FONTINFO Structure
The text rendering capabilities included as part of the TIGA extended primitives are very rich, providing the application writer with the ability to display
everything from simple, fixed cell type text, such as that used by dumb terminals and EGA, VGA graphics adapters, to the desktop publishing type (wysiwyg) text, where the height and width of characters, along with the style and
size can vary.
The fonts used for text rendering are a collection of characters having a
unique combination of height, width, style, and other attributes. The format
of these fonts are unique to TIGA and are described in the following paragraphs:
The characters within a font have an associated two-dimensional bitmap
that defines the shape of the character. When the text is rendered, On bits
(1 s) within a character bitmap are expanded to pixels in the active foreground color, as set by the seCfcolor function. Off bits (Os) are expanded
pixels in the background color. The format of a font is defined by the following data structure:
typedef struct
{
short magic;
/*
long length;
/*
char facename[32);
short first;
/*
short last;
/*
short maxwide;
/*
short maxkern;
/*
short charwide;
/*
short avgwide;
/*
short charhigh;
/*
short ascent;
/*
short descent;
/*
short leading;
/*
PTR
fontptr;
/*
short id;
/*
}FONTINFO;
TIGA Identifier
length of font in bytes
ASCII code of first character
ASCII code of last character
maximum character width
maximum character kerning amount
char. width (0 if proportional)
average width of characters
character height
ascent (how far above base line)
descent (how far below base line)
leading (row bott.to next row top)
address of font in GSP memory
id of font (set at install time)
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
The following is a description of the FONTINFO structure parameters. Parameters 8, and 10 through 13 are shown in Figure A-1.
1) magic
This field is an identifier for the data structure. It consists of three parts:
bits 00 - 01: data structure sub type
bits 02 - 07: data structure type
bits 08 -15: TIGA identifier
For the bitmap fonts described here, the magic identifier is filled in as
follows:
A-7
FONTINFO Structure
bits 00 - 01 : 0 (FONT subtype =bitmap)
bits 02 - 07: 1 (FONT)
bits 0.8 - 15: Ox80 (Indicates TIGA font format1.x)
For this particular font data structure, the magic number value is
Ox8040. In the future, TIGA may support outline or stroke fonts, in which
case the font subtype would change.
2)
length
The length of the entire font in bytes. This is useful when allocating
memory for a font and for reading it from disk.
3)
facename
A NULL terminated string of ASCII characters up to 32 long containing
the name of the font. Example: TI Roman, TI Helvetica, etc.
4) first
ASCII code of the first character defined in the font. For example, if first
was Ox20, the ASCII code for a space character, then that is the lowest
ASCII code for which a bitmap is defined in the font.
5) last
ASCII code of the last character defined in the font.
6) maxwide
The width of the widest character defined in the font.
7)
maxkern
The maximum kern for any character within the font, expressed as a
positive value. For example, if kerning was 3, then the maximum any
character will back up to overlap the previous drawn character is 3.
8)
charwide
The character width is the image width of the character, plus the space
separating this character from the next. If the character width is zero,
then the width of characters within the font varies. In that case an entry in
the offseVwidth table specifies the width for each character.
9)
avgwide
The average width of characters within the font. This is the cell width of
all defined characters within the font (not considering any kerning or extra intercharacter spacing) divided by the number of characters defined.
It is useful when selecting a font for a best fit at varying target resolutions.
A-a
TlGA Data Structures
FONTINFO Structure
10) charhigh
The character height is the sum of the ascent and decent. It is constant
throughout any particular font but may vary between fonts.
11) ascent
The ascent is the number of vertical pixels from the base line to the top of
the font cell.
12) descent
The descent is the number of vertical pixels from the base line to the
bottom of the cell.
13) leading
This term comes from the fact that typesetters often used strips of lead
to adjust spacing between rows of characters when building a plate to
be printed with a printing press. For bitmap fonts, this value is the number of pixels recommended by the font designer that should be skipped
between rows of characters, that is, if the leading is 3, then 3 pixels
should be skipped between the descent line of a row of characters, and
the ascent line of the row of characters drawn directly beneath.
A-9
FONTINFO Structure
Some of the fields in the font structure are illustrated in Figure A-1. The
numbers refer to the numbered sections in the parameter description.
Figure A-1. Bitmap Font Format
b
11
10
.....,1-+-...- 8
12
L 1-+--+--+-+-II--I---1--t-kL.......L.........L-J..-L.......L............L...-..I-L.........I-..I....L......L-.I
In addition, Figure A-1 illustrates the following font characteristics:
a) Base Line
The base line is an invisible reference line corresponding to the bottom
of the characters, not including the descenders.
b) Character Origin
The character origin is that part of a character corresponding to a specified drawing location. This origin may vary, depending on the text alignment attribute used to draw text. The default text alignment is relative to
the top left corner of the character cell. Alignment can also be set relative to the leftmost point on the character baseline by performing a call to
seCtextattr. Baseline origin is useful when a string of characters consists of different size or style fonts, in which case the baseline should
remain constant throughout the text.
c) Image Width
The image width is the number of bits ofthe portion of the character pattern bitmap containing the actual character image. This width does not
include any blank space to the left or right of the character when it is
displayed and can vary within a font and between fonts.
A-10
TIGA Data Structures
MODEINFO Structure
A.6 MODEINFO Structure
This structure contains all the configuration information that can vary on a
specific board. It is part of the configuration structure returned by
geCconfig (which returns only the MODE INFO for the currently installed
mode). The total possible modes can be inquired using geCmodeinfo.
typedef struct
{
ulong disP-Fitch;
ushort disp vres;
ushort disp-hres;
short screen wide;
short screen-high
ushort disP-Fsize;
ulong pixel mask;
ushort palet-gun depth
ulong palet-size;
short palet-inset;
ushort num-Fages;
short num offscrn areas;
ulong wksp addr; ulong wksp~itch;
}MODEINFO;
The MODEINFO structure consists of the following fields:
disP-Fitch
Display pitch: linear difference between two scan
lines in bits.
disp_vres
Vertical resolution in scan lines.
disp_hres
Horizontal resolution in pixels.
screen wide
Contains the width of the monitor in centimeters. For
systems where these dimensions are unknown, set
to 1.
screen_high
Contains the height of the monitor in centimeters. For
systems where these dimensions are unknown, set
to 1.
disP-Fsize
Pixel size.
pixel_mask
Contains a mask of the bits used in a pixel. It will normallycontain the value of 2tothepowerdisP-Fsize
minus 1, indicating that every bit of pixel data is pertinent. On some boards, the frame buffer may be arranged by 8 (disP-Fsize = 8) but with only 6 bits
implemented. In that case, pixel mask would contain
the value 63 (hexadecimal 3F).
palet_gun_depth
Number of bits per gun in palette.
A-11
MODEINFO Structure
palet_size
palet_inset
Number of entries in the palette.
For most systems, this field is set to O. For
TU~~.d.n7n_"'~C!grl
"'n~rrlC!
. . . . . _ - 1 _ ...... _ _ _ _ _ _
__• __ ,
,",hi"h C!tnro tho t"""'-_
n~lotto
•• - in
• • , •• _
••
_._._
••• _
II.
the frame buffer, this is the offset from the start of the
scan line to the first pixel data.
numyages
Number of display pages in multi-buffered systems.
num_offscrn_areas This is the number of offscreen memory blocks available. If nonzero, the~ it is used to allocate space for
the offscreen array, *,hich can be obtained from the
TMS340 via a call to the gecoffscreen_memory
function.
Starting linear address in memory of offscreen workspace area.
wkspyitch
A-12
Pitch of offscreen workspace area. If wkspy i tch =
0, then no offscreen workspace is currently allocated.
TlGA Data Structures
MONITORINFO Structure
A.7 MONITORINFO Structure
This structure is not of general interest to an application writer. It is used by
the OEM porting TIGA to its board to specify the values of the video timing
parameters for a particular mode. Note that this structure is board-specific.
An OEM is free to add to this structure its own OEM-specific video timing
information. This structure will invariably change for a TMS34020 version
ofTIGA.
typedef struct
{
ushort hesync;
ushort heblnk;
ushort hsblnk;
ushort htotal;
ushort vesync;
ushort veblnk;
ushort vsblnk;
ushort vtotal;
ushort dpyctl;
ushort screen delay;
ushort flags;}MONITORINFO;
The MONITORINFO structure consists of the following fields:
he sync
value loaded into the HESYNC 1/0 register
heblnk
value loaded into the HEBLNK I/O register
hsblnk
value loaded into the HSBLNK I/O register
htotal
value loaded into the HTOTAL I/O register
vesync
value loaded into the VESYNC I/O register
veblnk
value loaded into the VEBLNK I/O register
vsblnk
value loaded into the VSBLNK I/O register
vtotal
value loaded into the VTOTAL I/O register
dpyctl
value loaded into the DPYCTL I/O register
screen_delay Number offrames thatthe screen is blank when loading the
video registers. This allows a monitor time to synchronize
to the new timing before the screen is unblanked.
flags
Monitor desription flags. Current flags defined are 0 = color
monitor, 1 = monochrome monitor.
A-13
OFFSCREEN Structure
A.8 OFFSCREEN Structure
This
structure
defines
the
offscreen
areas
returned
by
the
geCoffscieen_memorj function.
typedef struct
{
PTR addr;
ushort xext;
ushort yext;
}OFF SCREEN_AREA;
The OFFSCREEN structure consists of the following fields:
A-14
addr
Address in TMS340 memory of an offscreen work area.
xext
X extension of the offscreen area in the current screen pixel size.
yext
y extension of the offscreen area in the current screen pixel size.
rIGA Data Structures
PAGE Structure
A.9 PAGE Structure
This structure is not of general interest to an application writer. It is used by
the OEM porting TIGA to his board to specify the start addresses of the display page (the value loaded into the display start 1/0 Register) and drawing
page (the value loaded into the offset B-file register). This structure is used
to support multiple display pages used by the page_flip function. Note that
this structure is board-specific and may change in future versions of TIGA.
typedef struct
{
PTR BaseAddr
ushort DpyStart
short DurnmyPad;
jPAGE;
The PAGE structure consists of the following fields:
BaseAddr
Base address of start of drawing page; this value is loaded into
the OFFSET B-file register.
DpyStart
Base address of start of display page; this value is loaded into
the Display Start 1/0 register.
DurnmyPad
16 bits to pad structure to power of 2 size.
A-15
PALET Structure
A.10 PALET Structure
This structure contains the red, green, blue, and intensity components for
a paiette entry.
typedef struct
{
uchar
uchar
uchar
uchar
}PALETi
ri
gi
bi
ii
This structure consists of the following fields of the palette entry:
A-16
r
Value of the red gun
g
Value of the green gun
b
Value of the blue gun
i
Value of the intensity
T/GA Data Structures
PA TTERN Structure
A.11 PATTERN -Structure
The PATTERN structure defines the pattern shape information passed to
the set-patn function.
typedef structure
{
ushort width;
ushort height;
ushort depth;
PTR data;
PATTERN;
This structure consists of the following fields:
width
Width of the pattern in bits.
height Height of pattern in bits.
depth
Depth (bits/pixel) of pattern.
data
Pointer to pattern data in TMS340 memory.
A-17
A-18
TIGA Data Structures
Appendix B
Graphics Output Primitives
This appendix describes some of the assumptions made in the design of
the TIGA graphics output primitives which are part of the extended primitives. It also describes the conventions adopted regarding the drawing,
mapping, and filling with pixels to represent mathematical functions on a video screen. This appendix includes the following sections:
Section
Page
8.1 Categories of Graphics Output Primitives ................ 8-2
8.2 Fill Patterns ....................................... 8-4
8.3 Mapping Pixels to XV Coordinates ..................... 8-5
8.4 Area Filling Conventions ............................. 8-6
8.5 Vector Drawing Conventions .. . . . . . . . . . . . . . . . . . . . . . . .. 8-7
8.6 Drawing Pen ...................................... 8-8
8.7 Color Selection .................................... 8-9
8-1
Categories of Graphics Output Primitives
B.1
Categories of Graphics Output Primitives
The graphics functions draw several shapes in a variety of styles. Table B-1
~l'·'u~.""rihn~
U""~VIIUv\;J
+hn
Lllg
fi~II"'n.
II~Ulv
+" .... ",.. "' .... ,..a ,..a ... ""',.,i""'iI"I ,,+,,1_ .... T_ ..... '_ D
L1tJ'Vi)
QIIU
UICl¥VIII~ ~LyIC.:J.
t") ,..""'_ ....,..
+&-.. __ ""' ___ _
IQUIV" U - , ".,VVV\:) lilt; i:)IIQiJU'i)
that can be drawn in a particular style. The column headers list the available
styles and the row headers list the available shapes; a check mark indicates
that a shape can be drawn with a particular style.
Table 8-1. List of Function Types and Drawing Styles
Function Types
Function
Name
line
oval
oval are
point
polygon
polyline
pieare
reet
seed
8-2
Description
A straight line.
Ellipse in standard position (major and minor axes para"el to coordinate
axes).
An arc of an ellipse in standard position, specified in terms of beginning and
ending angles.
A single pixel or pen image drawn at the indicated XV coordinate pair.
A filled region defined by a collection of straight edges. Both convex
polygons and arbitrarily complex polygons are supported.
A collection of straight lines. Figures made up of many lines can be drawn
more efficiently by using the polyline commands than by repeated calls to
the line functions.
Pie arc or wedge. Similar to ovalarc, but with addition of sides drawn from
center of ellipse to arc endpoints to produce a closed figure.
Rectangle with vertical and horizontal sides.
Fill connected set of pixels beginning at specified seed point.
Graphics Output Primitives
Categories of Graphics Output Primitives
Drawing Styles
Function
Name
draw
Draws figure outline one pixel wide using background color.
fill
Draws figure interior filled in solid background color.
frame
Draws frame in solid background color. Horizontal and vertical
thicknesses of frame border are both specified.
patnframe
Draws frame, using pattern in the foreground and background colors.
Horizontal and vertical thicknesses offrame border are both specified. The
pattern is programmable.
patnpen
Draws figure outline using pen and pattern in the foreground and
background colors. Pen size and pattern are programmable.
pen
Draws figure outline using pen in solid background color. Pen is
rectangular with programmable height and width.
patnfill
Draws figure interior filled with pattern in the foreground and background
colors. The pattern is programmable.
Description
Table 8-2. Checklist of Available Figure Types and Drawing Styles
Drawing Styles
Figure
Type
draw
pen
patnpen
fill
patnfill
frame
patnframe
line
..J
..J
..J
N/A
N/A
N/A
N/A
oval
..J
..J
..J
..J
..J
ovalarc
..J
..J
..J
piearc
..J
..J
..J
..J
..J
point
..J
..J
..J
N/A
N/A
polygon
N/A
N/A
N/A
..J
..J
polyline
..J
..J
..J
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
rectangle
..J
..J
..J
..J
..J
seed
N/A
..J
..J
N/A
N/A
N/A
N/A
8-3
Fill Patterns
B.2 Fill Patterns
Graphics functions
that include
patn as part of their names
draw with a pat-1 _.t. _ _ _
...,..1-. ___
_-I.L.- _ .. ,... .. , ... ,.. 1-:...
1:-1 __ 1 __
.&. _ _ _
: _ _ ... _ _
LI::III
III~Ll::dU
UI d
~UIIU
.LL _ _ _
\,;UIUI. I III:: IJdLLl::lI1
: _ _ ........ _ _ .&.I ••
I~
I : _ :...
\,;UII I::IILly IIIIIILI::U LU d
lOA 10
un-
map and is represented in memory as an array of 256 contiguous bits. The
bits in a pattern are listed in left-to-right order within a row, and rows are
listed in top-to-bottom order.
Figure B-1 shows an example of a pattern as it appears on the screen. The
small squares represent individual bits in the pattern; shaded squares represent 1s, and white squares represent Os. The bit at the top left corner is
the first bit (bit 0) in the pattern array. The bit at the lower right hand is the
last bit (bit 255) in the array.
Figure 8-1. A 16 x 16 Pattern
rl-rl-rT-rT-rT-rT'-Ti-TI
~4-
~
r
I
~
-I-t-I-t~
I
~
I
~
~
~-+~
I
I
Ti
+--1
.l..~
I
I
+--1
+1
+--1
.1.-'
I I
I
I
r~-
I
+--1
L..J
I
I
~-+--I
L~_L~_L~~_L~_L~_L~_L..J_L~
When a pattern is drawn to the screen, the Os in the bit map are replaced
with the background color, and the 1s in the bit map are replaced with foreground color. The pattern is mapped into 16 x 16 cells on the screen. The
X and Y coordinates at the top left corner of each cell are both multiples.
8-4
Graphics Output Primitives
Mapping Pixels to XY Coordinates
B.3 Mapping Pixels to XV Coordinates
Figure B-2 iUustrates the conventions that are used to map XY coordinates
to pixels on the screen. The filled area is a rectangle of width w = 5 and
height = 3, whose top left corner is located at XY coordinates (4,2). The fill
is performed by the following function call:
fill_rect(S, 3, 4, 2)
Pixels lying within the perimeter of the specified rectangle are turned on to
represent the fill area. By convention, X increases from left to right, and V
increases from top to bottom. The default drawing origin is at the upper left
corner of the screen. (The origin may be relocated at an arbitrary position
on or off screen with a call to the seCdraw_origin function.) The XV coordinates passed to graphics routines are constrained to be integer values. The
coordinate grid is overlayed on the screen so that integer XV coordinate
pairs coincide with pixel corners (not with pixel centers). The conventions
used for determining which pixels are selected to represent filled areas and
infinitely thin vectors are explained in the following sections.
Figure 8-2. Rectangle Fill
4
o
9
--!-----4----++x
----mm
I
2
5 ----
I
T
h=3
~
y
8-5
Area Filling Conventions
8.4 Area Filling Conventions
Figure B-3 shows a filled polygon, in which a fill-polygon function defines
the fiii area indicated by the straight edges in the figure. The ruie for determining whether a pixel is selected as part of the fill area is as follows: if the
center of the pixel falls within the mathematical boundary of the area, it is
turned on to indicate that is part of the fill area. (If a pixel's center falls precisely on the boundary between two areas, by convention the pixel is considered to be part of the area immediately below and to the right of the pixel).
Pixels whose centers lie outside the boundary are not considered part of the
fill region. The same principles are applied to the filling of other shapes (ellipses and thick lines drawn with a rectangular drawing pen, for example).
Graphics functions that follow the above conventions for filled areas are all
functions whose names include the modifiers fill, pen, or frame.
Figure B-3. Polygon Fill
o
3
5
7 8
....... x
--+---+--~-t--
y
8-6
Graphics Output Primitives
Vector Drawing Conventions
:7#~~W""W·VX:":":"X:Yf·;%";~:~;::::«<~::».:::::::::-;-»»mx~~«~~~~:».;~~x::::.~~~.:x:::::~..::~~~.«;::-;::::w/..:>::;;:;:;::~m:;::X%XXXM:;;;;;':;~::::-»::~~~~~~~~;
8.5 Vector Drawing Conventions
Points, lines, and arcs are defined mathematically to be infinitely thin. Because these figures contain no area, they are invisible if drawn using the
conventions for filled areas. A different set of conventions must be used to
make points, lines, and arcs visible. These are the vector drawing conventions (to distinguish them from the area filling conventions). Vector drawing
conventions apply to all functions whose names include the modifier draw.
The vector drawing conventions associate the point identified by the integer
coordinate pair (X,Y) with the pixel located to its lower right; that is, the pixel
whose center is located at coordinates (X+1/2,Y+1/2). For example, the
draw_point (7,10) command turns on the pixel at (7.5,10.5). As a second
example, the polygon from Figure B-3 is shown again in Figure B-4 but is
outlined rather than filled. (The draw_polyline function is used.) The points
selected to represent the right side of the polygon are indicated as small
black dots. The pixel to the lower right of each point is turned on to represent
the edge of the polygon.
A line or arc drawn using the vector drawing conventions consists of a connected set of pixels. This means that the line or arc is drawn as a continuous
set of pixels that connect (or touch) horizontally, vertically, or diagonally,
without gaps or holes in between.
Figure 8-4. Polygon Outline
o
7
--+---+--'--!--I--.x
9Y
8-7
Drawing Pen
8.6 Drawing Pen
The drawing commands that use vector drawing conventions can draw only
pixel thick lines and arcs. To draw lines and curves of arbitrary thickness,
a rectangular pen (or brush or logical pixel) is used. Graphics functions that
use the drawing pen have names containing the modifier pen.
The graphics commands can be used to set the drawing pen's height and
width to arbitrary positive, nonzero values. The pen is rectangular, and its
position is identified by its top left corner. For example, when a pen of width
wand height h draws a point at (X,Y), the resulting rectangle's top left corner lies at (X,Y), and its bottom right corner lies at (X+w, Y+h). The rectangular area covered by the pen is filled either with a solid color or with the current
pattern, depending on the function used.
The area under the drawing pen is filled according to the area-filling conventions described previously. When the width and height of the drawing pen
both equal 1, a line or arc drawn by the pen is. similar in appearance to that
drawn by a function following the vector drawing conventions. However, the
pen functions conform to the area-filling conventions, so a pen function can
track more faithfully the perimeter of a filled area than a corresponding draw
function.
For example, consider an ellipse defined by some width w, height h, and
coordinates (XI y).lf adraw_oval{w h, X, y) function call outlines a filled ellipse drawn by a fill_oval{w h, X, y) function, the draw_oval function may
not in all instances select the same perimeter pixels as the filled ellipse. This
can leave gaps between the filled area and the outline. In contrast, a
pen_oval{w h, X, y) function call follows the filled ellipse precisely, remaining flush to the ellipse at all points along the perimeter.
l
I
I
8-8
Graphics Output Primitives
Color Selection
B.7 Color Selection
The TIGA standard enables applications to be ported from one TMS340
board to another. One of the most difficult parts of the porting process is ensuring that the colors chosen for the application are distinguishable (if not
identical) when the application is run on another board. Palettes vary from
board to board, sometimes considerably. This section describes the TIGA
methodology concerning color selection.
The configuration structure returned in geCconfig, contains the
disPJ'size element, which the application can use to determine the number of colors that can be on the screen at any given time. The application
must interrogate this value to determine if this number is sufficient, and
double-up if necessary, painting different geometries with the same color.
Selecting the colors is done via the setJ)alet, or set-paleCentry functions
for a RAM-based palette. Because the palette may be ROM-based (making
it impossible to set the palette entries), the function_implemented function should be used on the set-paletfunctions prior to invoking them.lfthey
are not implemented, the palette can be assumed to be ROM-based and a
technique described later can be used to select colors. For RAM-based palets, each entry can be set via a call to seCpalet, which takes as its parameters an 8-bit value of red, green, blue, and intensity.
For color monitors, the intensity field is ignored and the R-G-B values are
used to load the palette entry. Because the palette may only use 4 or 6 bits,
it takes the most significant portion of the 8-bit palette entry to set the color.
The number of bits for each color gun is stored in the palet gun depth
field of the CONFIG structure. Alternatively, the get-palet function-will return the physical colors stored in each entry (as opposed to the logical colors
requested by the set-paletfunction).Thus, colors can be chosen and specified directly with this approach. For monochrome monitors, only the intensity field is used, to specify the level of the grey scale for each entry. Again,
the most significant bits are used when the palette entry size is less than 8
bits. Thus, for RAM-based palettes, the application should specify both a
color and monochrome values for each color index used.
For ROM-based palettes, the geCnearesCcolor function can be used to
inquire which color index to use. This function operates in reverse to the previous case where instead of setting an 8-bit red, green, blue color index with
a desired value, the nearest one to the desired value is returned to the calling application. Again, an independent grey-scale value for each color index
must also be requested for ROM-based monochrome monitors.
In summary, the application must test function_implemented on set-palet to determine whether the palette is ROM- or RAM-based. If it is
8-9
Color Selection
RAM-based, the application can select its palette directly and must do so
in both R-G-B and intensity values for monochrome monitors. If the palette
is ROM-based, the application must use geCnearesCcolor on each of its
desired palette entries to set up the color indices, again specifying both color
and monochrome values.
Finally, there is also a short cut: if the initj)alet function is implemented
(which is the case in RAM-based palettes with 4 bits-per-pixel or more), the
palette values after initialization are those stated in the initj)alet function.
The palette values are declared symbolically in an insert file tiga. h, and
if these values are acceptable, they can be used directly by an application.
8-10
Graphics Output Primitives
Appendix C
TIGA Reserved Symbols
l!WW
ilium
Section
Page
Co1 Reserved Functions
Co2 TIGA Core Primitive Symbols
Co3 TIGA Extended Primitive Symbols
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
C-2
C-3
C-5
C-1
Reserved Functions
C.1
Reserved Functions
TIGA currently reserves the following functions for internal use. Do not
chose function names that conflict with these_ Avoid calling functions from
an application program, since future versions of TIGA may not contain these
functions.
add_interrupt
add_module
del_all_modules
deUnterrupt
deLmodule
get_memseg
geCmodule
get_msg
get_state
getJstate
gm_is_alive
handshake
init_cursor
iniUnterrupts
iniCvideo_regs
makename
oem_init
read_hstaddr
read_hstadrh
read_hstadrl
read_hstctl
read_hstdata
rstr_commstate
save_commstate
seCmemseg
seCmsg
set_xstate
write_hstaddr
write_hstadrh
write_hstadrl
write_ hstctl
write_hstdata
C-2
T1GA Reserved Symbols
TIGA Core Primitive Symbols
C.2 TIGA Core Primitive Symbols
TIGA currently uses the following symbols in its core primitives and for the
TMS340 C environment. To guarantee succesful operation, do not use
downloadable extensions that conflict with any of these symbols.
If the extension is also to work with the extended primitives, then Section
C.3 should also be considered when selecting symbol names.
.bss
.data
.text
IsrCStk
IsrEntryTable
IsrSrv
_CoreFunc
_CursorlSR
_DEFAULT_PALET
_DefaultCursor
_DiTable
_Module
_NextDiEntry
_PageFliplSR
_TrapVector
_WaitScanlSR
_abort
_add_interrupt
_add_module
_atexit
_bottom_oCstack
_c_intOO
_check_dpyint
_clear_frame_buffer
_clear-page
_clear_screen
_comm_info
_config
_cpacket
_cpw
_defaulCsetup
_deLall_modules
_deUnterrupt
_deLmodule
_delay
_dm_clear_frame_buffer
_dm_clear-page
_dm_clear_screen
_dm_cpw
_dm_gecnearesCcolor
_dm-get-palet
_dm-9sp2gsp
_dm_init-palet
_dmJmo
_dm-peek_breg
_dm-poke_breg
_dm_rmo
_dm_seCbcolor
_dm_set_clip_rect
_dm_seCcolors
_dm_seCcurs_shape
_dm_seCcurs_state
_dm_seCfcolor
_dm_seCpalet_entry
_dm_seCpmask
_dm_set_ppop
_dm_secwindowing
_dm_set_wksp
_e nd_oCd ram
_envcurs
_envtext
_env
_exit
_flush_extended
_function_implemented
-geCcolors
-geCconfig
C-3
riGA Core Primitive Symbols
...,QeCcurs_state
...,QeCcurs_xy
...,Qet_fontinfo
...,QeUsrJ>riorities
...,Qet_module
...,QeCnearesCcolor
...,QeCoffscreen_memory
...,QetJ)alecentry
...,QetJ)alet
...,QeCpmask
...,QetJ)pop
...,QeCstate
...,QeCtransp
...,QeCvector
...,QeCwindowing
...,QeCwksp
...,Qetrev
...,Qsp2gsp
...,Qsp_calloc
...,Qsp_free
...,Qsp_malloc
...,Qsp_maxheap
...,Qsp_minit
...,Qsp_realloc
_iIIop
_iniCcursor
jniUnterrupts
_initJ)alet
_iniCtext
_inictrap_vectors
_iniCvideo_regs
-,mo
_main
_modeinfo
_monitorinfo
_offscreen
J)age_busy
J)age_flip
J)age
C-4
J)alet
J)alloc
-pattern
J)eek_breg
J)oke_breg
J>uCvector
_release_buffer
_rmo
_set_beolor
_seCclip_rect
_seCcolors
_seCconfig
_seCcurs_shape
_seCcurs_state
_seCfcolor
_seUnterrupt
_seCpalet
_setJ)aleCentry
_setJ>mask
_setJ>pop
_seCwindowing
_seCwksp
_setup
_stack_size
_start_oCdram
_strcpy
_sys_free
_sys_memory
_sysfont
_text_out
_transp_off
_transp_on
_video_enable
_waiCscan
cinit
edata
end
etext
TlGA Reserved Symbols
T1GA Extended Primitive Symbols
C.3 TIGA Extended Primitive Symbols
TIGA currently uses the following symbols in its extended primitives. Downloadable extensions that work with the extended primitives should not use
names that conflict with any ofthese symbols; this guarantee successful operation.
_arc_draw
_arc_fill
_arc_pen
_arc_quadrant
_arc_quad
_arc_slice
_bitblt
_c_intOO
_config
_delete_font
_dm_bitblt
_dm_draw_line
_d m_d raw_oval
_dm_draw_ovalarc
_dm_drawJ>iearc
_dm_draw_point
_dm_drawJ>olyline
_dm_draw_rect
_dm_filLconvex
_d m_fil Loval
_dm_fillJ>iearc
_dm_filLpolygon
_dm_filUect
_dm_frame_oval
_dm_frame_rect
_dm.-QetJ>ixeI
_dm_patnfilLconvex
_dm_patnfilLoval
_dmJ>atnfillJ>iearc
_dmJ>atnfillJ>olygon
_dmJ>atnfilUect
_dm_patnframe_oval
_dm_patnframe_rect
_dm_patnpen_line
_dmJ>atnpen_ovalarc
_dmJ>atnpenJ>iearc
_dmJ>atnpenJ>oint
_dm_patnpenJ)olyline
_dm_pen_line
_dmJ>en_ovalarc
_dmJ>en_piearc
_dmJ>en_point
_dmJ>enJ>0lyline
_dm_seed_fill
_dm_seed_patnfill
_dm_seCdraw_origin
_dm_setJ)atn
_dm_setJ)ensize
_dm_zoom_rect
_draw_eliparc
_draw_line
_draw_ovalarc
_draw_oval
_drawJ>iearc
_drawJ)oint
_drawJ)olyline
_draw_rect
_env
_envtext
_fill_convex
_filLeliparc
_filLoval
_fillJ>iearc
_fillJ>olygon
_filUect
_fill_shape
_frame_oval
_frame_rect
.-QeCenv
.-QeCpixel
.-Qet_textattr
.-Qsp_malloc
.-Qsp_realloc
_install_font
_onarc
J>atnJine
J>atnfilLconvex
J>atnfilLoval
_patnfillJ>iearc
_patnfillJ>olygon
_patnfilUect
_patnframe_oval
J>atnframe_rect
J>atnpen_line
J>atnpen_ovalarc
_patnpenJ>iearc
_patnpenJ>oint
_patnpenJ>0lyline
_pattern
_pen_eliparc
J>en_line
J>en_ovalarc
_penJ>iearc
_penJ>oint
_penJ)olyline
_seed_fill
_seed_patnfill
_selecCfont
_seCdraw_origin
_seCdstbm
_setJ)atn
_setJ)ensize
_set_srcbm
_seUextattr
_sin_tbl
_styled_line
_swap_bm
_sysfont
_text_width
_zoom_rect
C-5
C-6
TlGA Reserved Symbols
Appendix D
Porting TIGA
~~!i;;;;
;~.~~
The TIGA-340 Software Porting Kit (SPK) contains all source required to
port TIGA to any TMS340-based graphics board. The SPK is originally
shipped with a TI Software Development Board (SOB) compatible version
of TIGA. This version is used as an example, and a port of TIGA to a different
TMS340 board will involve modifications to the SOB port.
Before beginning the porting process, make sure you have the following
software tools installed on your system:
a
a
a
a
a
Microsoft macro assembler, version 5.0 or above
Microsoft MAKE utility
Microsoft linker
TMS340 assembler/linker, version 3.0 or above
TMS340 C compiler, version 3.0 or above
Porting TIGA consists basically of two tasks.The first is to modify the
host-side TIGA code (the TIGA communication driver or CD for short). The
second is to modify the TMS340-side code (the TIGA graphics manager or
GM for short). ' Each of these tasks have well-defined, step-by-step procedures that make porting TIGA to a different TMS340-based board a relatively simple operation. Because the GM rebuilding process relies on a functional CD, you must first port the CD before porting the GM.
Porting TIGA entails some knowledge of TIGA's architecture; therefore, it
may be helpful to refer to Section 1.3 for an overview of the components of
TIGA.
Section
Page
0.1
0.2
0.3
0.4
0-2
0-14
0-21
0-22
Porting the Communication Driver (CD) ....................
Porting the Graphics Manager ............................
Verifying Correct Operation ..............................
Debugging Your Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
0-1
Porting the Communication Driver
~W!«xs:;:;,....:"u'X:::-.xX;;:;:"~~
::::::WW~~~~lI'''::::~::.:lS!l
D.1
~"
'~f'~:::~~""""""
.•
~~'~~"~:::-~'f~:::;:;:;:~""~~X::X::~
Porting the Communication Driver
The TIGA communication driver (CD) is an MS-DOS Terminate-and-Stay-Resident (TSR) program that enables host communications
with the TMS340-based board. When the TIGA-340 SPK is installed, it
places all CD-specific files in the directory \tiga \cd. The files within this directory that may need modifications, along with a description of each, are
listed below:
oemdata. asm
Contains information defining each mode of operation
supported by the TMS340-based board
oeminit. asm
Contains board-specific initialization and inquiry functions
setvideo. asm Contains routines to set/get video mode information
sdbdefs. inc
Contains hardware-specific equates
Porting the TIGA CD involves modifications to each of the files above. The
following four sections describe in detail these modifications. Note that all
references to file names are assumed to be files within the \tiga \cd directory unless otherwise noted.
0.1.1
Modifying the
sdbd$fs. inc
File
The sdbdef s . inc file contains general information describing the hardware
aspects of the target TMS340-based board TIGA is being ported to. Before
making any modifications to this file, first copy it to a file that will be used to
describe your target board. Make sure to copy it within the \tiga \cddirectory and that its extension is . inc. For example purposes, assume the copied filename is newdef s . inc and use this filename throughout the communication driver porting guide.
Next, edit newdefs. inc; note that the file contains a number of equates defining constants that are used when the TIGA CD is rebuilt. Modify only
the constants described below. Modifications to any constant not listed below will result in a non-functioning communication driver:
D-2
OEMMSG
This message is displayed when the CD is installed. It describes the board on which TIGA is running. Be sure to enclose the description within double quotes.
SOB
If your target board is not the TI Software Development Board
(SOB), then set this constant to false (0).
MEMORY
This constant defines how the TMS340's host registers
(HSTDATA, HSTCTRL, HSTADRH, and HSTADRL) are accessed from the host. If your target board's host registers are
memory-mapped, set this constant to 1. Otherwise, they are
IIO-mapped, in which case the constant should be set to O.
Porting TlGA
Porting the Communication Driver
SYSTEM
If you want your TIGA CO to be compatible with Intel's SOS6
and later microprocessors, set this constant to false (0). If set
to TRUE (1), SOxS6 instructions will be used in the CO. This
results in faster execution but places a restriction on the host
processor type.
Next, modify the host portion defining the host port locations. These equates
define the host addresses (either memory or I/O) used to communicate with
the TMS340. Note that these addresses are hard-coded. If your board can
be configured to different host address memory locations, select one set of
addresses for the initial port (refer to section 0.1.19 for more information on
boards with mUlti-host port addressing).
Note that the HSTSEG address is valid for memory-mapped host register
boards only. Modify these constants to match your board's host register addressing.
The following values for the host register addresses are taken from the SOS
(memory-mapped) port.
HSTSEG
HSTAORL
HSTAORH
HSTOATA
HSTCTRL
Equ
Equ
Equ
Equ
Equ
OCOOOh ;
7EOOh;
7FOOh;
7000h;
7000h;
Host
Host
Host
Host
Host
port seg. (mem-mapped only)
address low
address high
data
control
The next two equates are used as timeout values in the CO. For most ports,
these values should suffice. However, if the call to gm_is_alive fails consistently, you may have to increase the GM_TIMEOUT value (see Section
O.1.1S for more information).
The next set of constants defines various monitors supported by the different operating modes of your board. Each monitor constant defines a bit flag
in a 16-bit word. Therefore, TIGA supports up to 16 monitors per mode.
The following monitor definitions were taken from the SOS port:
NEC
SONY
Equ
Equ
1
2
; SOB port supports two monitors, the
; NEC and the SONY Multisyncs
Here, two monitors are supported, the NEC Multisync and Sony Multisync.
Note that the first monitor constant has a value of 01 h, and the next has a
value of 02h. If additional monitors were supported, their values would be
04h, OSh, 10h, etc., up to SOh.
Next, modify the number of palette entries supported on your board in its default power-up mode. The SOS uses the TMS34070 4-bit color palette and,
therefore, has 16 palette entries.
Finally, one miscellaneous equate may need modification for your port.
STKSIZE - The host-side communication driver stack size may be modified
to suit your needs. The SOS port allocates 0400h bytes of stack.
D-3
Porting the Communication Driver
0.1.2 Modifying the oemdata. asm File
The oemdata . asm file contains descriptions of all the operating modes supported by your board. An operating rnode is deiined as a given resolution
with appropriate monitor timing values that support this resolution. The operating modes of the SDB port are used as an example. Use this example
as a guide to define the operating modes of your board.
The label Setup_Table defines the start of the operating mode specific data.
The SDB port supports four operating modes: the first is a 640 x 480 x 4 resolution mode (1 display page) and the second is a 448 x 480 x 4 (2 display
pages) mode. These two modes are duplicated forthe NEC and Sony Multisync monitors. Each mode supported by your board must be defined by a
label following the Setup_Entry label. These mode labels are used to actually define the mode-specific data.
;
; Define number of modes and mode/setup tables
;
Setup Table
Setup-Entry
Setup-Entry
Setup-Entry
Setup=Entry
Equ This Word
Mode 640x480x4N
Mode-448x480x4N
Mode-640x480x4S
Mode-448x480x4S
Start of
SDB mode
SDB mode
SDB mode
SDB mode
setup
0 for
1 for
0 for
1 for
table
NEC
NEC
Sony.
Sony.
0.1.3 Defining the Mode-Specific Information
Each board operating mode has its own set of data describing the following
items:
[JI
Monitor identification flags
[JI
Mode-specifiG information
[JI
Monitor timing information
[JI
Display page information
[JI Offscreen memory information
For example, mode 0 of the SDB port is defined as follows:
D-4
Porting TIGA
the Communication Driver
; * * *' * * ** ***** *' ** * * *' * *' * *** * *' * ** * * * * * * *' * *** ** *** * * * * * * * * * * * * * * * * ** * * * * * * * *** * * * * *** * * *
;
SDB Mode 0: 640x480x4, 1 page for NEC Monitor
:***********************************************************************************
;
SETUP Structure
Mode_640x480x4N
Setup_Struc
Mode_Info
Monitor_Info
Page_Info
Off_screen
Off_Screen
Off_Screen
Equ
This Byte
: Mode 0 setup structure
1 GOCh, 480,640,27,20 14, OFh, 4, PALET _ENTRIES I lOCh, 1,2 1 OBOOh, lOaOh
OlBh,OlCh,OCCh,OCDh,OOlh,018h,OlF8h,OlFAh,OFOIOh,30,O
00000100h,OFFFCh
OOOOOBOOh,640/4,480
00000D80h, 160, 480
001EOOOOh, 1024, 32
End_Setup
Each operating mode of your board has a similar block of information defined, one block for eack mode defined in the Setup_Table. Use the following instructions to modify each mode information block for your board.
0.1.4 Defining the Mode Label and Setup_Struc Structure
The mode setup structure starts with a label identifying the mode. This label
is the same as the one added in the Setup_Table entries earlier.
Next, initialize the Setup_Struc macro with the valid monitors supported by
this mode. These monitor constants were defined earlier in the
newdefs. inc file.
0.1.5 Defining the Mode_Struc Structure
Next, modify the mode-specific information. The Mode_Info structure contains parameters describing this operating mode. The structure is defined
in the file struct. inc as follows:
Mode Struc
Mode-Disp Pitch
Mode-Disp-Vres
Mode-Disp-Hres
Mode-Screen Wide
Mode-Screen-High
Mode-Disp Psize
Mode-Pixel Mask
Mode-Palet-Gun Depth
Mode-Palet-Size
Mode-Palet-Inset
Mode-Num Pages
Mode-Num-Offscrn
Mode-Wksp Address
Mode-Wksp-Pitch
Mode-Struc
Struc;
Dd?
Dw?
Dw?
Dw?
Dw?
Dw?
Dd?
Dw?
Dd?
Dw?
Dw?
Dw?
Dd?
Dd? ,
Ends;
Mode information structure
Display pitch (bits)
Vertical resolution (pixels)
Horizontal resolution (pixels)
Screen width (centimeters)
Screen height (centimeters)
Display pixel size
Pixel mask
Palette gun depth (bits)
Palette size
(For TMS34070 palette only)
Number of screen pages
Number of off-screen areas
Temporary Workspace Address
Temporary Workspace Pitch
End of Mode Struc structure
The Mode_Num_Pages field describes the total number of display pages
supported forthis mode. Multiple display pages are used in TIGA to support
animation via the page_flip function. Section D.1.7 provides additional information.
0-5
Porting the Communication Driver
The Mode_Num_Offscrn field describes the total number of x-y offscreen
memory blocks available for use by an application. Section 0.1.8 describes
these memory blocks in greater detail.
The fields Mode_Wksp_Address and Mode_Wksp_Pitch describe the offscreen workspace. This workspace is a 1-bit-per-pixel bitmap with the same
horizontal and vertical dimensions as the visible screen. It is used by the
filtpolygon and patnfill_polygon functions as a working buffer. If enough
offscreen memory is available to support this workspace, then this offscreen
memory block should be the first Off_Screen structure defined (see Section
0.1.8) and the Mode_Wksp_Address and Mode_Wksp_Pitch fields should
be initialized to point to this block.
0.1.6 Defining the Monitor_Info Structure
Next, modify the Monitor_Info specific data for this mode. This structure is
defined in the struct. inc header file as follows:
Monitor Struc
Monitor-Hesync
Monitor-Heblnk
Monitor-Hsblnk
Monitor-Htotal
Monitor-Vesync
Monitor-Veblnk
Monitor-Vsblnk
Monitor-Vtotal
Monitor-Dpyctl
Monitor-Screen Delay
Monitor=Flags Monitor Struc
Struc;
Dw?
Dw?
Dw?
Dw?
Dw?
Dw?
Dw?
Dw?
Dw?
Dw?
Dw?
Monitor information structure
End horizontal sync signal
End horizontal blank signal
Start horizontal blank signal
Horizontal total (Characters)
End vertical sync signal
End vertical blank signal
Start vertical blank signal
Vertical total (Scanlines)
Display control register
Screen delay (Frames)
Monitor type flags (BitO
:O=color, l=mono) Bits 1-15
reserved
Ends; End of Monitor_Struc structure
The structure element, Monitor_Screen_Oelay, specifies the delay (in
frames) that the screen will be blanked when the video registers are loaded.
This allows the monitor time to synchronize to the new timing values.
The structure element Monitor_Flags specifies whether the monitor is color
(when the LSB is a 0), or monochrome (when the LSB is 1). Bits 1 -15 are
reserved. The palette routines use this flag to choose between the intensity
level or the R, G, B values specified in the palette structure.
0.1.7 Defining the Page_Info Structure
The next structure, Page_Info, contains information defining the available
display pages for this particular mode. Each mode must have at least 1 display page defined. For each display page, a corresponding Page_Info
structure must be defined. The actual number of disptay pages is defined
in the Mode_Num_Pages field of the Mode_Struc structure. The Page_Info
structure is defined in the file struct. inc as follows:
0-6
Porting TlGA
the Communication Driver
Page Struc
Page=Base_Addr
Struc
Dd
Page DpyStart
Page-Pad
Page=Struc
Dw
Dw
Ends
?
?
?
Page information structure
Page base address
(linear bit address)
Page start offset
Page dummy pad bytes
End of Page_Struc structure
Each page is defined by two elements:
1)
The base address (loaded into the B-file register OFFSET) when this
page is being written to
2) The display start (loaded into the DPYSTRT I/O register) when this
page is being displayed
Using Mode 1 (448 x 480 x 4,2 pages) of the SDB port as an example, two
display pages are supported. These page definitions are as follows:
Page Info
Page=Info
OOOOOlOOh,OFFFCh; Page 0
00000900h,OFFF4h; Page 1
The TIGA core function, page_flip, enables the selection of the current display and drawing page. For example, page_flip(O,1) selects page 0 as the
display page and page 1 as the drawing page. Therefore, B-file register
OFFSET would be loaded with 0900h (the base address for page 1) and
the DPYSTRT 10 register with OFFFCh (the display start for page 0).
Note:
Even though the Page_Info structure contains 16 bits of pad, this value
should not be entered as part of the Page_Info information.
Be sure and note the maximum number of display pages defined in any operating mode of your board. This value is required when porting the TIGA
graphics manager.
0.1.8 Defining the Off_Screen Structure
TIGA enables an application to use offscreen memory as a bitblt storage or
temporary workspace though the geCoffscreen_memory function. This
function returns information describing the available offscreen memory
areas that are defined in the OFF_SCREEN structure.
The OFF_SCREEN structure is defined in the file struct. inc as follows:
Screen Struc
Screen-Address
Screen X Ext
Screen-Y-Ext
Screen-Struc
Struc
Dd?
Dw?
Dw?
Ends
Screen information structure
Start (linear) off-screen memory
X extent of memory (pixels)
Y extent of memory (pixels)
End of Screen Struc structure
0-7
The actual number of offscreen areas for a particular mode is defined in the
Mode_Num_Offscrn field of the Mode_Struc structure. For each offscreen
area, a corresponding Off_Screen structure is defined. If your board does
not contain any offscreen areas, then no off-screen structures need be defined.
Using Mode 0 of the SOB port as an example, 3 offscreen memory areas
are available and are defined as follows:
Off Screen OOOOOBOOh,640/4,480 ; Alloc.to offscrn wksp 0
Off-Screen OOOOOD80h,160,480
; Offscreen area 1
Off=Screen OOlEOOOOh,1024,32
; Offscreen area 2
Note that the first Off_Screen block defined is intended to be used for the
offscreen workspace. The Mode_Wksp_Pitch and Mode_Wksp_Addrfields
of the Mode_Info structure for ModeO are initialized to point to this block.
Be sure and note the maximum number of offscreen areas defined in any
operating mode of your board. This value will be required later when porting
the TIGA graphics manager.
0.1.9 Defining OEM-Specific Data
If you have any other mode-specific data, it should be added to the operating mode data using the OEM_Data structure. This structure, defined in the
macro. inc file, follows the Off_Screen structure data. To use the
OEM_Data structure, modify the number of parameters expected by the
OEM_Data macro in the macro. inc file. Then, supply the OEM-specific
data using the OEM_Data macro. A corresponding change is required in the
graphics manager portion of TIGA to support this new data.
Note:
In the SOB port, no OEM_Data is defined, but an example of its usage is
shown.
0.1.10 Completing Modifications to oemdata. asm
Repeatthe above instructions to define all operating modes for your particular board.
After the last mode information block, global data variables used by the CD
are declared. The Previous_Mode variable may require changing. This variable is used to store the TMS340 board emulation mode (that is, EGA, VGA)
prior to loading TIGA. Because the SOB does not support emulations, the
Previous_Mode is set to TIGA. However, if your board does support emula0-8
Porting TlGA
the Communication Driver
tions, then initialize this variable to the emulation mode in which the board
powers up. If the emulation is configurable by DIP switches, then an appropriate function called within the oem_init function (see Section 0.1.11)
should be written to initialize this variable. Valid constants for emulation
modes are defined in the file \tiga\include\tiga.h file.
Finally, the DRAM_Start and DRAM_End symbols need to be initialized to
the largest block of DRAM on the target board.
DRAM_End is used to store the high-water mark in memory where the system stack resides. The address should be double-word aligned and must
not be higher than OFFFFDFEOh, since memory above this address is reserved in the TMS340 memory map. This address should also be equal to
the bottom_oCstack value in the link control file of the graphics manager.
0.1.11 Modifying the oeminit.asm File
The oemini t . asm file contains functions used to initialize a specific
TIGA-compatible TMS340 target board. The functions in oemini t . asm
shipped with the TIGA Software Porting Kit perform specific initializations
for the SOB and therefore require modifications for your particular board.
The oemini t . asm file contains the following four board-specific initialization
functions:
OEM_lnit
Initializes the board.
OEM_Sense
Returns 10 of current monitor in use.
MonitoUnit
Initializes the TIGA mode table with all valid modes for current monitor in use.
Video_Enable
Switches video from EGANGA to TIGA.
0.1.12 Modifying the OEM_lnit Function
The OEM_lnit function performs all initializations necessary to put the target
TMS340-based board in a state where the TIGA graphics manager can be
loaded to it. The TIGA communications driver calls the OEM_lnit function
when it is initially loaded.
Using the SOB port as an example, the OEM_lnit function first halts the
TMS340, flushes the cache, and sets the INCR and INCW bits in the
TMS340's HSTCTL register. It then switches on the SOB's shadow RAM,
clears the interrupt enable I/O register so that the board TMS340 can be
halted later, and clears the TMS340's CONTROL register.
Note the comment within the OEM_lnit function regarding the setting of the
CONTROL register. It is extremely important to initialize the CONTROL
D-9
Porting the Communication Driver
register properly to support the type of ORAM refresh cycles used on the
board.
Note:
00 not modify the code related to the high-water mark.
0.1.13 Modifying the OEM_Sense Function
The OEM_Sense function is used to return the 10 of the monitor that is connected to the target TMS340-based board. The valid monitor lOs were previously defined in the newdefs. inc file.
In the SOB port, there is no way to sense the type of monitor using the SOB.
However, on other boards, OIP switches or monitor sense lines are available for this purpose. This example function searches for a -s command
line argument and sets dx to the Sony id if found. Otherwise, dx is set to
NEC.
0.1.14 Modifying the Monitor_lnit Function
The monitoUnit function calls OEM_Sense to get the current monitor connected to the target TMS340-based board. It then steps through the list of
all modes defined in the Setup_Struc structures (defined in oemdata. asm)
and puts the indices of those modes that support the current monitor into
space allocated in Mode_Table (defined in oemdata. asm). This, in essence,
defines the total number of modes available for the current monitor in use.
This function requires no modifications except when more than 16 monitors
are supported.
0.1.15 Modifying the Video_Enable Function
This function invokes a graphics manager function that does nothing on the
SOB, because there is no EGA emulation implemented on the SOB. Video_Enable is shown here as an example of its implementation. If the video
on your board can be switched directly from the host side, then modify this
function to do so. Otherwise, as illustrated in the SOB port, call the
Video_Enable graphics manager function to perform the video switch.
0.1.16 Modifying the setvideo. asm File
The
two functions within setvideo. asm, seCvideomode and
geCvideomode, require porting only for those TMS340-based boards
which support other graphic modes (that is, EGA, VGA, etc.). Because the
D-10
Porting TfGA
Porting the Communication Driver
SOB does not support any other graphics modes, comments are given within the set video . asm code to offer suggestions on alternative graphics
mode support.
0.1.17 Miscellaneous Communication Driver Porting Issues
The following sections describe additional modifications that may be needed for porting the TIGA communications driver to your specific board.
0.1.18 Default Timeout for gm_is_alive Function
The file error. asm contains the function gm_is_alive. The purpose of this
function is to check if the TIGA graphics manager (the part of TIGA which
runs on the TMS340-side) is alive and running. It does this by installing its
own error trap, calling one of TIGA's core primitives, and then waiting a certain period for the TIGA primitive to complete. If the function does not complete in the time allotted, the error handler is called and false (0) is returned,
indicating a non-functioning graphics manager.
The delay time is defined by the constant GM_TIMEOUT in the file
newdefs. inc and is set in the SOB port to 0.5 seconds. This timeout value
may have to be lengthened on those boards with monitor screen delays
longer than 30 frames (see Defining the Monitor_info Structure in Section
0.1.6).
This potential problem is evident when an application calls a function requiring the use of TIGA's linking loader TIGALNK (that is, create_aim) immediately following a call to seCvldeomode(TIGA,INITIALlZE). Because the
call to seCvideomode reloads the video timing registers (using the delay
defined by the monitor delay amount), and TIGALNK first checks if the TIGA
graphics manager is alive (via gm_is_alive), there is a chance that this
delay will cause gm_is_alive to fail. TIGALNK then returns an error message indicating that the ALM file could not be created (in this example).
0.1.19 Using Boards with Multi-Addressable Host Port Locations
TMS340-based boards with multi-addressable host port locations were
mentioned in Section 0.1.1. Because the host port addresses are hardcoded in the newdefs. inc file, only one of the address sets are supported.
However, by making some simple modifications, programmable host port
addressing is possible.
First, five 16-bit variables must be declared in the CD data section (in the
file data. asm). These variables are
HstCtrlAdr
HstAdrlAdr
dw
dw
?
?
; HSTCTRL host address
; HSTADRL host address
0-11
Porting the Communication Driver
HstAdrhAdr
HstDataAdr
HstSegAdr
dw
dw
dw
?
?
?
HSTADRH host address
HSTDATA host address
Segment address (memory map only)
Next, these addresses must be initiaiized before any iiO is performed
through the TMS340's host port.
The file macro. inc contains all the macros that perform I/O functions
through the TMS340 host port. For example, Write_HSTDATA is a macro
which writes 16 bits of data to the TMS340 HSTDATA register. For memory
mapped boards, ax is assumed destroyed by these macros. For 1/0mapped boards, ax and dx are assumed destroyed. Currently, these macros assume hardcoded addresses for the host port locations. To modify the
macros, use the following Write_HSTDATA example as a guideline:
Write HSTDATA
Macro
Reg, Seg
Local SegReg
Ifb
SegReg Equ
Else
SegReg Equ
Endif
push
bx
; We must save bx (not assumed destroyed)
mov bx,ds:HstDataAdr
Load bx with address of HSTDATA
If
MEMORY
If reg passed == bx
Ifidni ,
mov ax, Reg
then copy to ax
and send it
mov SegReg: [bx],ax
Else
mov SegReg: [bx],Reg
otherwise, send the reg
Endif
Else
Set IO [bx]
Set io address
If reg passed == ax
Ifidni ,
out dx,ax
then output ax
Else
mov ax, Reg
otherwise, move reg to ax
and output ax
out dx,ax
Endif
Endif
pop
bx
Restore bx
Endm
You must also search through each of the .asmfiles inthe \tiga\cddirectory and replace all occurrences of HSTSEG with the appropriate value in the
HstSegAdr variable.
0-12
Porting TlGA
Porting the Communication Driver
0.1.20 Rebuilding the Communication Driver
Rebuilding the TIGA communication driver is a simple operation. First, edit
the file makecd. bat. This batch is designed to rebuild the communication
driver for the SBD and must be modified for your board as follows:
Step 1: Change lines 3 and 4 to check for an id for your board. Also,
change the label from SOB to a label for your board.
Step 2: Change the label on line 7 to your new label.
Step 3: Modify the description on line 10.
Step 4: Change line 15 to copy newdefs. inc into defs. inc.
After making the above modifications, enter makecd yourid from the
MS-DOS command line from the \tiga \cd directory. Note that your idis the
identification added to the makecd.bat batch file in step 1 above.This rebuilds the TIGA communication driver tigacd. exe and copies it into TIGA's
main directory \tiga.
D-13
Porting the Graphics Manager
D.2 Porting the Graphics Manager
The TIGA Graphics Manager (GM) is the portion of TIGA that resides on the
+-.--+ -..--",;,..,.. h ...... _ ...
.,..J
~;""n\
All filn~ ~~~I'\,..i~+o.'" u,i+h
IIVIV...., .... V ..-:;JIUvj. r\11 I I Iv"';' U~";''''''''IU.'',""U "'11.'1
I+r..." TlAC'lAn
Lal~C'L~IQ"'III"'O UVQIU \LIIC'
+ho
.I'V
TI~A
I ........ "
GM are installed in the \ tiga \gm directory, with specific portions of the GM
split into subdirectories under the \tiga \gm directory as follows:
Directory
\ tiga \gm
\tiga\gm\corprims
\tiga\gm\extprims
\tiga\gm\sdb
Contents
TIGA graphics manager command executive
TIGA GM core primitives
TIGA GM extended primitives
TIGA GM board-specific functions
It is suggested that another directory be created underthe \t iga \ gm directory to contain board-specific functions for your particular board. For example, assume a directory called \ tiga \gm\newgm exists and that all of the
files from the \tiga\gm\sdb directory have been copied into the
\tiga\gm\newgmdirectory.
The majority of the modifications necessary to port the TIGA GM are made
to the board-specific functions in the \ tiga \gm\newgm directory.
The following sections describe in detail these modifications. Note that all
references to filenames are assumed to be files within the \ tiga \gm \newgm
directory unless otherwise noted.
The board-specific functions in the \tiga\gm\newgmdirectory are grouped
into four main categories:
[:'I Clearing video memory,
0.2.1
[:'I
Palette-specific functions,
[:'I
Configuration functions, and
[:'I
Miscellaneous functions.
Video Memory Initialization Functions
clearfrm.asm The clear_trame_buffer function uses the fastest possible method to clear the entire frame buffer to a specified
color. In the SOB port, shift register transfer cycles are
used. If this is not possible on the target TMS340 board,
use a FILL (see the clear_screen function in the file
clearscr. asm for information on how this is done).
clearpag. asm The clear_page function uses the fastest possible method
to clear the entire current drawing page to a specified color.
Because shift register transfers cannot be used to clear
D-14
Porting TIGA
Porting the Graphics Manager
only a portion of the entire frame buffer on the SOB, the
SOB port simply calls the clear_screen function, which
performs a FILL. The port of this function should use shift
register transfers if possible.
clearscr. asm The clear_screen function uses the fastest possible meth-
od to clear the visible portion ofthe current drawing page to
a specified color. Although this file is not grouped with the
other board-specific, video memory initialization functions,
it may be ported to utilize a faster screen clearing method.
The SOB port uses the FILL instruction.
0.2.2 Palette-Specific Functions
The following functions provide the capability to utilize a color palette on the
target board. The SOB board uses the TMS34070 color palette, and these
functions are therefore written to use the TMS34070. They must be modified if your board has a color palette other than the TMS34070.
getpalet. c
The function geCpalet returns the values in the global palette array palet stored in TMS340 memory. Generally, this
function does not require any porting.
ini tpale. c
The function init-palet sets the palette to EGA default colors. It should replicate these colors through the entire palette. On the SOB, this is trivial since it has only16 entries.
Where there are more entries, this will need to be done in a
loop. If the palette is in ROM and no initialization is possible, this function should not be implemented and its entry
should be cleared in the \tiga\gm\primdefs. c file to insure function_implemented returns false.
setpalet. asm The set-palet and set-paleCentry functions within
setpalet . asm perform initialization of a TMS34070 pal-
ette which stores the palette information in the frame buffer.
Note that the data stored in the global array palet (declared in oem. c) is the physical color. The LS 4 bits are
masked because they are not used in the TMS34070. If the
palette is in ROM and no initialization is possible, this function should not be implemented and its entry should be
cleared in the \tiga\gm\primdefs.c file to ensure
function_implemented returns false.
Note that the palet routines use the monitor_flags field of the
moni tor info structure to determine ifthe monitor is color or monochrome.
This field selects the use of either the r, g, b values or the i value to initialize the palet.
0-15
Porting the Graphics Manager
0.2.3 Configuration Functions
config.c
The gecconfig function does not require porting. The
_....... ___,,;_ '11 __+: __ .-,.'IIt ...___ .: ..___ .....: __ ;, '''_ ..... L-.. __ ......... _
.::tg,_"'""' .... y IUII\.fLlUIl IIlay U:;'"'IUIlIICi
II YUUI UUClIU u:;quires specific initializations for a particular mode. This initialization can be performed wherever convenient within
the seCconfig function.
""UILIII~
An example of an initialization that may be required for your board involves
adding support for OEM mode data specified in the Setup structure. If OEMspecific data was added to the oemdata. asm file during the CD port (via the
OEM_Data structure, see Section D.1.9), then the graphics manager portion of TIGA must be modified to support this data. Normally, the code to
handle OEM-specific data is added to the secconfig function.
oem. h
This file contains constants and type definitions used to initialize and maintain mode information in the graphics
manager. The constants VIDEO_MEMORY_START,
VIDEO_MEMORY_END, and PALET_ENTRIES should
be modified to match your board specifications.
PALET_ENTRIES should contain the number of palette
entries in your default board mode. The three shared
memory·
constants,
SHARED_MEM_SIZE,
SHARED_HOST_ADDR, and SHARED_GSP_ADDR
should be initialized to values other than 0 if the board supports shared memory. If it does not, (as in the SDB port),
initialize to O.
The DRAM_RM_RR constant defines the DRAM refresh mode and refresh
rate. It is ORed with TIGA's default CONTROL value to initialize the TMS340
processor CONTROL register. The value of this constant in the SDB port,
OxOS, specifies RAS-only refresh (RR field = 0) and refresh to occur every
64 local clock periods (RM field = 01).
The communication buffers, used byTIGA to buffer commands between the
host and the TMS340, are declared statically in TMS340 memory. The
oem. h file contains two constants that define the size and number of these
buffers.
The NUM_COMM_BUFFERS constant defines the number·of communication buffers. Each communication buffer contains the information for one
command. Therefore, the more communication buffers defined, the more
commands that can be queued. The recommended minimum is three communication buffers.
The COMM_BUFFER_SIZE constant defines the size (in bytes) of the data
area in each communication buffer. The value assigned to this constant
D-16
Porting TIGA
Porting the Graphics Manager
must be at least 1K (1024) bytes and a multiple of 2. This minimum size
is necessary to ensure that data less than 1024 bytes long can be sent to
the TMS340 processor without fear of overflowing the communication buffer.
The MAX_PAGES and MAX_OFFSCREEN constants must be set to the
maximum number of pages and offscreen areas, respectively, in any operating mode defined in the communication driver port (see Section D.1.7,
which defines the PAGE_INFO Structure and Defining the OFF_SCREEN
structure for more information). This is to insure that there is sufficient
memory allocated to download these structures to the GM.
The HEADER and SETUP structures may require modification to support
any OEM-specific data added to the CD port (via the OEM_Data structure,
see Section D.1.9 for more information).
oem.c
This file contains the initial configuration and setup structures.
The data contained in these default structures is used to initialize the TIGA environment when the graphics manager is
initially executed (that is, the GM banner message is displayed), and also to statically define an area in TMS340
memory where mode information from the host is downloaded. This configuration is overwritten almost immediately
thereafter by the current mode information downloaded by the
host. The data in Default Modeinfo, Default Monitor info, Default Page and Default Offscreen should be initialized with one
mode from the oemdata. asm file in the communication driver.
In a future release of TIGA, the copying of the setup structure into a fixed
length default structure may well be changed to use system heap, thereby
enabling the setup structure to be dynamic in size. This initial configuration
is also useful because it enables debug messages to be printed from the
graphic manager's main loop during debug of the GM port.
0.2.4 Miscellaneous Functions
initvide.c
The function inievideo_regs initializes the video
registers for the new mode. This function does not
require porting unless the target board needs initialization of some other board-specific latches relating to video timing.
videnbl.c
In the SDB port, the video_enable function does
nothing. However, for a board that uses a separate
frame buffer for alternate graphics modes (that is,
EGA), the Video_enable function switches the
D-17
Porting the Graphics Manager
back-end to display the frame buffer for the correct
mode. It is called by the host side function seCvideomode.
sysfont.asm
Two system fonts are supplied with the TIGA port:
sys640. asm and sysl024. asm. The former is designed for low resolution (640 by 480 and below),
the latter for high resolution (1024 x 768 and
above). To select a particular system font, copy it
into the file sysfont. asm. This is the files that will
actually be assembled and linked into the graphics
manager when it is rebuilt.
trapvect.asm
The functions within the trapvect. asm file perform I/O with the TMS340 processor interrupt trap
vectors. This file requires modifications if the interrupt traps for your board are located in ROM or are
not contiguous in memory from TMS340 address
OFFFFFC0016 (trap 31) to OFFFFFFE016 (trap 0).
\tiga\gm\primdefs.c This file defines all implemented core functions
provided by theTIGA graphics manager. The addresses of functions that are not implemented in
your specific board port should be cleared and
their declarations removed to insure function_implemented will return false for these functions.
Consult the function_implemented description
in Chapter 3 for a list of functions that are likely not
to be implemented on all boards.
\tiga\gm\gmdefs.c
The
only
modification
required
in
the
\tiga\gm\gmdefs.c file is the pathname of the
OEM-specific header include file (line 10). Modify
the pathname of this file to include your OEM-specific definitions.
\tiga\gm\tigagm. inc The include file \tiga\gm\tigagm. inc contains a
label named OEMMSG as an identifying string for
your board. Modify the string to the name of the
board being ported to. This message is displayed
when the graphics manager is executed.
There are two possible modes of cursor operation in TIGA. The default
mode (recommended method) is a display interrupt driven cursor. This entails the cursor being redrawn every frame, which is acceptable for most systems. In very high resolution displays, however, the overhead of a display
D-18
Porting T1GA
Porting the Graphics Manager
interrupt cursor may be unacceptable, in which case a hide/show cursor
mechanism may be used. To obtain a hide/show cursor, modify the value
of NON_OLCURSOR from 0 to 1. The latter cursor flashes quite noticeably,
whereas the display interrupt cursor is solid.
0.2.5 Rebuilding the Graphics Manager
Rebuilding the TIGA graphics manager consists of four parts:
1)
Rebuilding the TIGA core primitives
2)
Rebuilding the TIGA extended primitives
3)
Rebuilding the board-specific functions
4) Rebuilding the TIGA command executive
The batch file \tiga \gm \makegm. bat does all of this automatically. However, since this batch file and all others associated with rebuilding the GM were
designed for the SOB port, a few changes are required before rebuilding
your GM port.
\tiga\gm\makegm.bat
This is the main batch file that rebuilds the TIGA
GM. It is invoked from the DOS command line with
one argument.
The following SOB port dependencies may have to
be modified:
a
a
a
a
The batch file argument id of SOB
The board-specific directory (\tiga \gm\sdb)
and make file name (sdblib.mak)
The board-dependent library filename
(\tiga \gm\sdb\sdb . lib)
Comments
After building the GM, makegm. bat automatically attempts to create the new
GM symbol file \tiga\tiga340. sym by first running tiga.cd and then
tigalnk / cs.lt is forthis reason thatthe CO port should be completed prior
to porting the GM.
\tiga\gm\tigagm.cmd
This is the link command file used by gsplnk. exeto
build the TIGA graphics manager out file
tigagm. out.
The following SOB port dependencies may have to
be modified:
D-19
Porting the Graphics Manager
I:l The board-dependent library filename
(\tiga\gm\sdb\sdb.lib)
I:l The values assigned to the labels:
_start_oCdram
_bottom_oCstack
_stack_size
_e nd_oCd ram
I:l The values assigned to program:
origin
length
I:l Comments
Note:
The label_bottom_oCstack must be double-word (32-bit) aligned, (that is,
the 5 LSBs must be zero) and must correspond to the address DRAM_End
in the communication driver. See Section D.1.1 O.
\tiga\gm\tigagm.mak
This make file rebuilds the GM command executive
and links all portions of the GM to form the out file
tigagm.out.
The following SDB port dependency may have to be
modified:
The board-dependent library filename
\tiga\gm\sdb\sdb.lib located in the list of
dependencies for tigagm. out.
\tiga\gm\newgm\sdblib.mak
This make file rebuilds the board-dependent library.
The following SDB port dependencies may have to
be modified:
I:l The filename of the make file itself
I:l The filename of the board-dependent library
(sdb.lib)
After modifying the above files, change your current directory to \ t iga \gm
and enter: makegm yourid, where yourid is the board identifier you added
to the makegm.bat batch file. The TIGA graphics manager is then built and
the output file tigagm.out copied into the TIGA system directory \tiga.
D-20
Porting T1GA
Verifying Correct Operation
0.3 Verifying Correct Operation
Included with the TIGA SPK is a comprehensive test suite designed to test
different aspects of a TIGA port. This test suite can be run from the
\tigapgms\tests directory by entering tigatest from the DOS command
line.
It is suggested that the tests be run in the order displayed on the menu and
that problems be fixed as they are encountered.
After verifying correct operation of the test suite, try some of the other test
programs supplied in the tigapgms directory.
0-21
Debugging your Port
0.4 Debugging Your Port
The TIGA communication driver can be easily debugged using Microsoft's
CodeView(R) or comparabie debugger. The TiGA graphics manager can
be debugged by using your board's TMS340 debugger. The following are
some suggestions for debugging the TIGA GM:
The TIGA graphics manager initializes all TMS340 trap vectors upon startup. This can cause havoc with your debugger, which may initialize trap vectors (that is, for single-step capability) before loading and executing the
TIGA GM. To overcome this problem, modify the IniCtrap_vectors function in the file \tiga\gm\sdb\trapvect .asm so that trap vectors used by
your debugger are not overwritten.
After displaying its startup message, the GM then waits for handshaking to
occur with the host. If necessary, a host TIGA application should be written
that performs the handshake with the TIGA GM as follows:
#include
main()
{
set videomode(TIGA,NO INIT);
handshake();
-
After performing the handshake, the GM command executive waits for a
TIGA command from the host.
D-22
Porting TlGA
Appendix E
Debugger Support for TIGA
i
Iii
mil
l:!!iil!
iCil
TIGA is the definitive interface standard for applications software written
to run on the TMS340 architecture, but it gives no guidelines to developers
of software with special hardware accessing requirements, such as debuggers.
A set of routines has been included in TIGA to meet the often unique needs
of debugger developers. This appendix contains the initial TIGA debugger
routines developed.
Section
Page
E.1 TIGA Debugger Routines ................................ E-2
E.2 Compatibility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. E-12
E-1
TlGA Debugger Routines
ssmx::::-~w;::s~-::s::msWh~.'::::X::X:;~;:lX:l'~S::::~'::~';:;:'W":w""#~~W~~'@.&H~~;~:~;::::W/.::;-;:;::-;-.:sxx::-,//.u/ffi.m::~ili::'»~:::;''''':'~·S.%
E.1
TIGA Debugger Routines
A separate document describing the use of the debugger functions will be
pubiished in the future. The debugger routines deveiopment wiii be based
on the following criteria and on any user feedback received:
1) Portable to any TIGA environment, which potentially includes all
TMS3401 0- and TMS34020-based PC graphics displays.
2) Transparent to share the TMS3401 O's host interface registers with an
application being debugged that uses the host interface for communication between host and TMS340 resident software.
3)
Able to support the symbolic debug of RLMs (Relocatable Load Modules), if running in an environment where the TIGA graphics manager
is active.
The following is a list of the routines in TIGA that provide debugger support:
[J
get_vector: Get contents of GSP trap vector
[J
seCvector: Set contents of GSP trap vector
[J
seCxstate: Set GSP execution state
[J
gecxstate: Get GSP execution state
[J
geCmemseg: Get high/low bounds of GSP memory segment
[J
seCmemseg: Set high/low bounds of GSP memory segment
[J
seCmsg: Send a message to the GSP
[J
geCmsg: Receive a message from the GSP
[J
save_commstate: Save communication state
[J
rstr_commstate: Restore communication state
[J
oem_init: Initialize board-specific data
Note:
The geCvector and seCvector functions are described in Section 3.3 because their usefulness is not restricted to debuggers.
E-2
Debugger Support for TlGA
Return High/Low Bounds of GSP Memory Segment
Syntax
void get_memseg( addrlo, addhi );
unsigned long *addrlo, *addrhi;
Type
Core
gecmemseg
Description The geCmemseg function is not for general use. It is provided for use by
debuggers and other such tools that have special hardware accessing requirements. This function returns the low and high bit addresses of a usable
block of TMS340 memory. Note that if the TIGA graphics manager is active
(determined by a call to gm_is_alive) then this block of memory has been
appropriated by the TIGA memory manager, and should not be used. Instead, a call to TIGA should be used to allocate usable memory. The two
arguments, addrlo and addrhi, are pointers to unsigned longs where the
TMS340 addresses are to be placed.
E-3
gecmsg
Return a Message from the GSP
Syntax
unsigned short get_msg();
Type
Core
Description The geCmsg function is not for general use. It is provided for use by debug-
gers and other such tools that have special hardware accessing requirements.This function receives a 3-bit message from the TMS340. The message is located in bits 0 - 2 of the returned value. The fourth bit, bit 3, is
an interrupt bit and indicates that an interrupt was requested by the host.
E-4
Debugger Support for TlGA
Return GSP Execution State
Syntax
unsigned short get_xstate();
Type
Core
get xstate
Description The geCxstate function is not for general use. It is provided for use by de-
buggers and other such tools which have special hardware accessing requirements. This function returns the current TMS340 execution state. The
returned 16 bits are described below:
Example
~
Bit 0
1 if TMS340 is halted, 0 if not.
~
Bit 1
1 if NMI set, 0 if not
~
Bit 2
1 if NMIMODE set, 0 if not
~
Bit 3
1 if cache flushed, 0 if not
~
Bit 4
1 if cache disabled, 0 if not
~
Bits 5-15
Reserved for future use
#include
main()
{
if (cd_is_alive(»
{
if (get_xstate() & 1)
printf("GSP is halted\n");
else
printf("GSP is running\n");
E-5
rstr_commstate Restore Communication State
Syntax
unsigned short rstr_commstate();
Type
Core
Description The rstr_commstate function is not for general use. It is provided for use
by debuggers and other such tools that have special hardware accessing
requirements. This function restores the state of TMS340 communications
to the state it was in after a previous call to save_commstate.The function
returns zero if unable to save the state, nonzero if it is successful.
E-6
Debugger Support for TIGA
Save Communication State
Syntax
unsigned short save_commstate();
Type
Core
save commstate
Description The save_commstate function is not for general use. It is provided for use
by debuggers and other such tools that have special hardware accessing
requirements. This function saves the state of TMS340 communications.
The function returns zero if unable to save the state, nonzero if it is successful.
E-7
seCmemseg
Set High/Low Bounds of GSP Memory Segment
Syntax
void set_memseg (addrlo, addhi) i
unsigned long addrlo, addrhii
Type
Core
Description The seCmemseg function is not for general use. It is provided for use by
debuggers and other such tools that have special hardware accessing requirements. This function sets the low and high bit addresses of a usable
block of TMS340 memory. It should be called after using some of the
memory returned by geCmemseg to reflect the new memory size.
E-8
Debugger Support for T1GA
Set a Message from the GSP
Syntax
void set_msg ( msg );
unsigned short msg;
Type
Core
secmsg
Description The seCmsg function is not for general use. It is provided for use by debug-
gers and other such tools that have special hardware accessing requirements. This function sends a 3 bit message to the TMS340. The message
is located in bits 0 - 2 of argument msg. The fourth bit, bit 3, is an interrupt
bit and requests a host interrupt into the TMS340.
E-9
set xstate
Set GSP Execution State
Syntax
void set_xstate (options) ;
unsigned short options;
Type
Core
Description The seCxstate function is not for general use. It is provided for use by de-
buggers and other such tools which have special hardware accessing requirements. This function sets the current TMS340 execution state. The returned 16 bits are described below:
[J
Example
Bit 0
1 to halt the TMS340, 0 to let it run
[J Bit 1
1 to invoke an NMI, 0 to clear NMI
[J
Bit 2
1 to set NMIMODE,
[J
Bit 3
1 to flush cache,
[J
Bit 4
a to stop cache flush
1 to disable cache, a to enable cache
[J
Bits 1 -15
Reserved for future use, must be set to Os
a to clear NMI
#include
main()
{
if (cd_is_alive())
{
set_xstate(l);
set_xstate(O);
E-10
/* halt the GSP
/* run the GSP
*/
*/
Debugger Support for TIGA
Initialize Board-Specific Data
Syntax
void oem_in it ()
Type
Core
oem_init
Description This function halts the TMS340 and performs any board-specific initialization prior to loading a COFF file.
E-11
Compatibility Functions
E.2 Compatibility Functions
It is recommended that the compatibility functions not be used by an application programmer, Their functions can be performed by the entry points in
the previous section and by the communication functions described in
Chapter 3. These functions talk directly to TMS3401 0 hardware, which is
not present on the TMS34020, and their functionality can be emulated only
on the TMS34020. However, since the TMS3401 0 has been available for
some years now, many utilities have been written that interface to the
TMS34010 hardware directly. If these utilities are to be ported to TIGA, in
the understanding that they may not run correctly on the TMS34020 or other
future products, then these functions may provide a quick method of porting.
read_hstaddr
Read the TMS3401 0 host address register
read_hstadrh
Read the TMS3401 0 host address high register
read_hstadrl
Read the TMS3401 0 host address low register
read_hstctl
Read the TMS3401 0 host control register
read_hstdata
Read the TMS3401 0 host data register
write_hstaddr Write to the TMS34010 host address register
E-12
write_hstadrh
Write to the TMS3401 0 host address high register
write_hstadrl
Write to the TMS3401 0 host address low register
write_hstctl
Write to the TMS3401 0 host control register
write_hstdata
Write to the TMS3401 0 host data register
Debugger Support for rIGA
==-
Read the TMS34010 Host Address Register
Syntax
unsigned long read_hstaddr();
Type
Core
read_hstaddr
Description This function returns the contents of the host address register of the
TMS34010.
E-13
read hstadrh Read the TMS34010 Host Address High Register
Syntax
unsigned short read_hstadrh();
Type
Core
Description This function returns the contents of the host address high register of the
TMS34010.
E-14
Debugger Support for T1GA
Read the TMS34010 HostAddress Low Register
Syntax
unsigned short read_hstadrl();
Type
Core
read_hstadrl
Description This function returns the contents of the host address low register of the
TMS34010.
E-15
read hstetl
Read the TMS34010 Host Control Register
Syntax
unsigned short read_hstctl();
Type
Core
Description This function returns the contents oj the host controi register of the
TMS34010.
E-16
Debugger Support for T1GA
Read the TMS34010 Host Data Register
Syntax
unsigned short read_hstdata () ;
Type
Core
read_hstdata
Description This function returns the contents ofthe host data register of the TMS3401 O.
E-17
write_hstaddr Write to the TMS34010 Host Address Register
Syntax
void write_hstaddr(value)
unsigned long value;
Type
Core
Description This function writes the 32-bit value supplied into the host address register
of the TMS3401 O.
E-18
Debugger Support for TIGA
Write
to the TMS34010 Host Address High Register write_hstadrh
.,.".
Syntax
void write_hstadrh(value)
unsigned short value;
Type
Core
Description This function writes the 16-bit value supplied into the host address high reg-
ister of the TMS3401 O.
E-19
write_hstadrl Write to the TMS34010 Host Address Low Register
Syntax
void write_hstadrl(value)
unsigned short value;
Type
Core
Description This function writes the 16-bit value supplied into the host address low reg-
ister of the TMS3401 O.
E-20
Debugger Support for T1GA
Write to the TMS34010 Host Control Register
Syntax
void write_hstctl (value)
unsigned short value;
Type
Core
write hstctl
Description This function writes the 16-bit value supplied into the host control register
of the TMS3401 o. Note that in order to function properly, TIGA expects the
values of the INCR, INCW, and LBL bits in host control to be set in a particular manner. If these bits are modified, they must be restored prior to invoking another TIGA function or the TIGA environment may be corrupted.
E-21
write hstdata
Write to the TMS34010 Host Data Register
Syntax
void write_hstdata(value)
unsigned short vaiue;
Type
Core
Description This function writes the 16-bit value supplied into the host data register of
the TMS34010.
E-22
Debugger Support for TIGA
Appendix F
Glossary
Ii:
ADI'I'M: Autodesk Device Interface, an interface specification used for developing customized drivers for peripheral devices for Autodesk products.
A_DIR: An MS-DOS environment variable; identifies the directories
searched when you specify include and macro files for the TMS340 family assembler.
AI: Application Interface. A part of TIGA consisting of a linkable application library and include files that reference TIGA type and function definitions. The AI provides the interface between an application and the TIGA
communication driver (CD).
m
ALM: Absolute Load Module, an extension to the TIGA standard in the
form of TMS340 object code. It is linked to an absolute memory location
and stored in a memory image format. An application can load the ALM
to invoke custom TMS340 functions.
bitblt: Bit aligned block transfer. Transfer of a rectangular array of pixel
information from one location in a bitmap to another with potential of appiying 1 of 16 logical operators during the transfer.
bitmap: 1. The digital representation of an image in which bits are
mapped to pixels. 2. A block of memory used to hold raster images in a
device-specific format.
CD: Communication Driver. This is a terminate-and-stay-resident program that runs on the PC. It is specific to a particular board and is supplied
by the board manufacturer with the board. The CD contains functions that
F-1
Glossary
are invoked by an application's calls to the AI to communicate via the PCbus to the target TMS340 board.
C_D!R:
An MS-DOS environment variable: it identifies the directories
searched when you specify include files for the TMS340 C-compiler and
when specifying object directories for the TMS340 linker.
COFF: Common Object File Format. An implementation of the object file
format of the same name developed by AT&T. The TMS340 family compiler, assembler, and linker use and produce COFF files.
command buffer: An area of TMS340 memory used by the TIGA-340 interface buffer data passed by the application and read by the TMS340
processor.
command number: An identifier of a function to be invoked by an application when the function resides on the TMS340 board. The command
number consists of three parts: 1) The function type, which specifies the
format that the parameters are referenced by the TMS340. 2) The module number, which acts as an identifier to the group of functions. Every
DLM receives a module numberwhen it is installed. 3) The function number, which specifies the specific function within the DLM that is to be invoked.
communication buffer: See command buffer.
configuration: The hardware setting of the TMS340 board, comprising
display resolution, pixel size, palette size, availability of shared memory,
etc.
coprocessor: Microdevice that offloads numeric operations from the
main processor to speed up overall operation. The TMS34082 is a coprocessor to the TMS34020. The two devices are tightly coupled together.
The coprocessor adds to the register and instruction capability of the
TMS34020, resulting in improved handling of floating point arithmetic. In
this manual, the TMS340 processors are occasionally defined as coprocessors to the 80x86 PC processor. This is to emphasize that the
TMS340 is a programmable processor and can offload much of the burden of the graphics processing and bitmap manipulation from the host
PC.
core primitives: A group of TIGA functions that can always be invoked
by an application after TIGA has been installed, as opposed to the extended primitives, which need to be loaded explicitly by an application.
C-packet mode: A method of passing parameters in TIGA from the host
to a function on the TMS340 board. It enables the parameters pushed
onto the host stack to appear on the TMS340 program stack, as if the
function had been invoked locally to the TMS340.
F-2
Glossary
Glossary
m
cursor: In TIGA, this refers to a graphics cursor, which is an icon on the
screen. The cursor is generally under mouse control and is used as a
pointing device in a graphics application.
DDK: Driver Developer's Kit. A product provided by Texas Instruments to
allow software developers to write application drivers that interface to the
TIGA-340 standard. It consists of a TIGAdriverforthe Texas Instruments
software development board (SDB), the TIGA application interface (AI),
and example programs.
direct mode: A TIGA mode that is the fastest mechanism to transfer parameters from the host to a function on the TMS340 board. The parameter data is passed in raw form to a TIGA communication buffer, and the
TMS340 function receives a pointer to the data.
DlM: Dynamic Load Module. The DLM is a key part of TIGA's extensibility. The module consists of a collection of custom C or assembly routines
that are not otherwise part of TIGA; thus, they are an extension of TIGA's
functionality. The DLM is loaded by an application so that the custom
TMS340 functions can be invoked by the application. There are two types
of modules: Relocatable Load Modules (RLiv1s) and Absolute Load Modules (ALMs).
environment or drawing environment: A group of attributes consisting
of drawing origin, pen size, fill pattern, source and destination bitmaps,
and line style.
environment variable: An MS-DOS variable that can have a string assigned by an end-user with the MS-DOS SET command. This string can
be interrogated by a program running under MS-DOS.
extended primitives: A portion of the TIGA interface functions that can
be invoked only by a TIGA application after they have been explicitly installed.They consist of mostly drawing primitives.
extensibility: A key feature of TIGA consists of an expandable function
set. An application programmer can write custom TMS340 functions,
which can be installed at runtime and invoked from the host application
in the same manner as the standard TIGA functions.
F-3
Glossary
II
font: A set of characters in predefined format that contain alignment information, allowing the text routines to produce a visually correct representation of a given character string.
frame buffer: A portion of memory used to buffer rasterized data to be
output to a CRT display monitor. The contents of the frame buffer are often referred to as the bitmap of the display and contain the logical pixels
corresponding to the points on the monitor. screen.
GM: Graphics Manager. A TMS340 object file specific to a particular
board, supplied with the board by the manufacturer. It contains a command executive to process commands sent from the application, and a
set of primitives. Some of these are integral TIGA primitives and some
may be user extensions.
m
GSP: Graphics System Processor. A TMS340 family-based system with
the processing power and control capabilities necessary to manage highperformance bitmapped graphics.
heap: An area of memory that a program can allocate dynamically.
D
ISR: Interrupt Service Routine. A routine to service an interrupt on the
TMS340 processor. The most common interrupt is that produced by the
display interrupt, but other interrupts are available from the host processor and from two external interrupt pins for window violation. ISRs can
be downloaded by an application as part of a DLM .
ISV: Independent Software Vendor. A company that produces software
products. In this guide it refers to a company that writes a software product to interface directly with TIGA. ISVs include Microsoft, Autodesk, etc.
II
LIM expanded memory. This system was developed by Lotus, Intel, and Microsoft, to define a hardware and software interface for 80x86
processors running under MS-DOS. LIM provides access to bankswitched random access memory.
LIM TM:
F-4
Glossary
Glossary
linking loader: A program called TIGALNK that runs under MS-DOS and
is an integral part of TIGA. It loads and links a dynamic load module with
user extensions to TIGA into the TIGA Graphics Manager on the
TMS340.
memory management: Also referred to as dynamic memory allocation.
It consists of a group of functions that are used for heap management.
mode: A particular configuration of a board. An individual board may have
several modes, for example: 1024-pixels x 768-lines at 8 bits-per-pixel,
or 640-pixels x 480-lines at 4 bits-per-pixel.
m
MS·DOS TM: Microsoft Disk Operating System. A PC-based operating
system. Because MS-DOS and PC-DOS are esentially the same operating system, this manual uses the term MS-DOS to refer to both systems.
NMI: Non-Maskable Interrupt.The NMI cannot be disabled; it is usually
generated by a host processor.
OEM: Original Equipment Manufacturer. A hardware manufacturing company. In this user's guide, it refers to companies that manufacture PC
graphics add-in boards with a TMS340 processor on them.
offscreen memory: The part of the frame buffer not being output to a display. A frame buffer, although typically one contiguous area of linear
memory, can be viewed as a rectangular area with a specific pitch. Each
row of the rectangular area corresponds to a row of pixels on the screen.
If the length is less than the frame buffer pitch, or if there are more lines
in the frame buffer than are displayed on the screen, there will be an area
of the frame buffer not used for display. This area is named offscreen
memory. Offscreen memory does not include the program memory used
to store code and data.
origin: The zero intersection of X and Y axes from which all points are calculated.
F-5
Glossary
page: Some TMS340 boards may have enough memory in their frame
bufferto hold two complete copies ofthe bitmap outputto the screen. This
technique, sometimes called double buffering, allows one area of the
screen to be displayed (the display page) while another is being updated
(the drawing page). When the drawing is completed, the drawing and display pages are interchanged (page flipping). The flip is synchronized to
the vertical blank time to ensure a flicker-free display. This technique is
useful for producing animation sequences.
palette: A digital-lookup table used in a computer graphics display for
translating data from the bitmap into the pixel values shown on the display.
pattern or fill pattern: SomeTIGA graphics output primitives use a pen
to fill an area with a pattern rather than a solid color. The pattern is specified as a 1-bit-per-pixel map. When the pattern is drawn, Os in the bitmap
are drawn using the current background color, and 1s are drawn using
the current foreground color.
pen or drawing pen: SomeTIGA graphics output primitives use a pen to
draw an outline. The drawing pen has application-selectable width and
height. The area covered by the pen can be solid or pattern-filled.
pixel processing: A logical or arithmetic combination of two pixel values
(source and destination).
PixBlt: Pixel Block transfer. Operations on arrays of pixels in which each
pixel is represented by one or more bits. PixBlt operations are a superset
of bitblt operations and include not only commonly used logical operations, but also integer arithmetic and other multi-bit operations.
plane: (Also bit plane or color plane). A plane is a bitmap layer in a display
device with multiple bits per pixel. If the pixel size is n bits and the bits in
each pixel are numbered Oto n-1, plane 0 is made up of bits 0 from all
the pixels, and the plane n-1 is made up of bits numbered n-1 from all
the pixels. A layered graphics display allows planes or groups of planes
to be manipulated independently of the other planes.
Ii]
raster-op: See pixel processing.
RLM: Relocatable Load Module. An extension to the TIGA standard in the
form of TMS340 object code. The RLM file is in COFF file format. It is
loaded by an application so that the application can invoke custom
TMS340 functions.
F-6
Glossary
Glossary
SOB: Software Development Board. A PC-compatible board manufactured by Texas Instruments. The SOB contains a TMS3401 0 graphics
processor. The two TIGA kits (DDK and SPK) produced by Texas Instruments use the SOB as their target board.
SDK: Software Developer's Kit. A Texas Instruments product that allows
software developers to write TMS340 code. The SDK may be used to develop a TIGA extension, but it is equally applicable for programmers who
wish to develop stand-alone TMS340 applications. This kit contains the
DDK and tools such as the C compiler, assembler, and linker.
shift-register transfer: A transfer between RAM storage and the internal
shift register in a video RAM.
SPK: Software Porting Kit. A Texas Instruments product that allows manufacturers of TMS340-based boards to port TIGA to their board. It contains all TIGA software source code as well as the SDK.
swizzle: The reversal of every bit in a byte. This is required to convert from
big-end ian processors (where the smallest numbered bit in a word is
most significant), to little-end ian processors (where the smallest numbered bit in a word is least signiflcant).
symbol table: A file containing the symbol names of all the variables and
functions on the TMS340 side of TIGA. The symbol table is used by the
linking loader when it is downloading an RLM to resolve references to
those symbols. This enables the functions in the RLM to call TIGA primitives that are resident on the TMS340 board.
II
TIGA TM, TIGA-340 TM : Texas Instruments Graphics Architecture. A software interface standard that allows a host processor to communicate
with the TMS340 graphics processors that are typically resident on an
add-in board. The current implementation of TIGA is for the PC market
and interfaces the 80x86 processor running under MS-DOS with the
TMS340.
TIGACD: This is the file name of the executable program containing the
communication driver that you run to install TIGA on your system.
TIGALNK:
See linking loader.
time-out: An application invokes a TIGA TMS340 function by placing a
command number and appropriate parameters in one of several comF-7
Glossary
mand buffers. After loading several commands, the command buffers
may be full; the host has to wait until the TMS340 finishe~ the current
command and frees up a buffer. Also, ifthe function invoke~needs to return data back to the appiication, the appiication must wait untii the
TMS340 completes the command. If the application waits longer than a
specified time, a time-out warning message is displayed.
A family of graphics system processors and peripherals manufactured by Texas Instruments.
TMS340:
First-generation graphics processor manufactured by Texas
Instruments.
TMS34010:
Second-generation graphics processor manufactured by
Texas Instruments.
TMS34020:
TMS34070:
First-generation color palette manufactured by Texas Instru-
ments.
Floating-point unit manufactured by Texas Instruments; coprocessor to the TMS34020.
TMS34082:
transparency: When a pixel with the attribute of transparency is written
to the screen, it is effectively invisible, and does not alter that portion of
the screen it is written to. For example, in a pixel array containing the pattern for the letter A, all pixels surrounding the A pattern could be given
a special value indicating that they are transparent. When the array is
written to the screen, the A pattern, but not the pixels in the rectangle containing it, would be invisible.
trap vector: A specific 32-bit address in TMS340 memory that contains
the address of an interrupt service routine.
Terminate and Stay Resident. A type of program that runs under
MS-DOS. When it terminates, this type of program leaves a portion of itself in memory.
TSR:
window:
A specified rectangular area of virtual space on the display.
workspace: An area of memory that is equal in size to a 1-bit-per-pixel
representation of the current display resolution. Polygon fill functions use
the workspace as a temporary drawing area before drawing on the
screen. The workspace can reside either in offscreen memory or in heap.
F-8
Glossary
~n»:JOOc%Z
m] is
*
:
Index
1I'JmJm~!IlnU!llllGq!ll!ll~§ml§l1l'!!!!W
W!!!!lmWdl
i i
II I:
:m
:
B
absolute load module, ALM, 3-12, 3-22,
3-96, 4-2, 4-8, 4-48, 4-49
installation, 4-8, 4-43
application interface, AI, 1-4, 2-12, 3-2
DDK,2-5
SPK,2-5
attributes, 3-5, 3-6, 3-9, 3-75, 3-76, 3-95,
3-167,3-179,3-180,4-33, A-7
m
background color, 3-5, 3-55, 3-141, 3-143,
3-145,4-33
bitblt, 3-8, 3-9, 3-14, 3-155, 3-166, 3-184,
4-36
Ii
C-packet, 4-10,4-11,4-13,4-18,4-36, 4-41
cc utility, 2-12
cd_is_alive, 3-3, 3-16, 3-86
cI,2-17
clear functions, 3-4
clear_frame_buffer, 3-4, 3-17
clear-page, 3-4, 3-18, 3-19
clear_screen, 3-4, 3-17, 3-18, 3-19
cltiga batch file, 2-12
COFF loader, 3-86, 4-47
comm_buff_size, 3-57, A-3
command buffer, 1-5, 3-3, 3-8, 3-35, 3-40,
3-44,3-57,3-112,3-118,3-129,3-135,
4-12,4-13, 4-i6, 4-18, 4-36
::il:
1m
.
lmJmJm;r;rmlWW@I~
~rel]j[
;c::::::::rea~~::::
command number, 1-5, 3-103, 4-4, 4-10,
4-11, 4-13, 4-36, 4-43
communication buffer. See command buffer
communication driver, CD, 1-4, 2-5, 2-6,
2-10,2-11,3-3,3-8,3-16,4-12,4-13,
4-16,4-47
communication functions, 1-4,3-11
compatibility functions, E-12
CON FIG structure, 3-3, 3-6, 3-8, 3-10, 3-14,
3-35,3-40,3-44,3-57,3-64,3-66,3-69,
3-90,3-108,3-112,3-118,3:129,3-135,
3-144,4-13,4-16
See also MODEINFO structure
cop2gsp,3-11,3-20
coprocessor, 3-12, 3-20, 3-57, 3-81
core primitives, 1-6,2-5,2-8,3-2,4-10,4-11,
4-32, C-3
cp_alt, 4-13, 4-14
cp_cmd, 4-13, 4-14
cp_ret, 4-13
cpw, 3-5, 3-21
create_aim, 3-12, 3-22, 3-159, 4-2, 4-8, 4-9,
4-32,4-43,4-47
create_esym, 3-12, 3-24, 4-32, 4-47
currenCmode, 3-57, 3-108, A-3
cursor, 3-10, 3-59, 3-60, 3-90, 3-145, 3-146,
3-152,3-153,4-33,4-44, A-5
m
debugger functions, E-2
delete_font, 3-9, 3-26
demonstrations and examples, 2-6
device_rev, 3-57, A-3
Index-1
Index
m
debugger functions, E-2
deiete_font, 3-9, 3-26
demonstrations and examples, 2-6
device_rev, 3-57, A-3
direct mode, 4-10, 4-11,4-12,4-18,4-32,
4-36,4-41
disp_hres, 3-58, A-11
dispJ)itch, 3-14, 3-58, A-11
dispJ)size, 3-58, 1+11, 8-9
disp_vres, 3-58, A-11··
displaLmem_end, 3-57, A-4
displaLmem_start, 3-57, A-3
dm_cmd,4-18
dmjpoly, 4-17, 4-28
dmJ)alt, 4-24
dmJ)cmd, 4-25, 4-41
dmJ)get, 4-23
dmJ)oly, 4-17, 4-26
dm_pret, 4-25
dmJ)snd, 4-21
dmJ)str, 4-24
dmJ)trx, 4-24
dm_ret, 4-20
draw_line, 3-7, 3-27, 8-2, 8-7
draw_oval, 3-7, 3-29, 8-2, 8-7
draw_oval arc, 3-7, 3-31, 8-2, 8-7
drawJ)iearc, 3-7, 3-33, B-2, B-7
drawJ)oint, 3-7, 3-34, 8-2, 8-7
drawJ)olyline, 3-7, 3-8, 3-35, 8-2, 8-7
draw_rect, 3-7, 3-37, 8-2, 8-7
drawing origin, 3-6, 3-60, 3-61,3-72,3-142,
3-145,3-153,3-154, A-6, 8-5
driver, 2-1
driver developer's kit, DDK, 1-2, 2-4
subdirectories, 2-5
system requirements, 2-2
environment variable, 2-11 , 2-17, 3-22, 3-24,
3-49,3-61,3-96,3-99,3-101,4-7,4-36,
4-47
autoexec modification, 2-9
extended primitives, 2-5, 2-8, 3-2, 3-3, 3-50,
3-99,4-10,4-11,4-43,8-1, C-5
DDK,2-5
extensibility, 1-3, 1-4, 1-6,3-12,3-22,3-24,
3-49, 3-50, ~-63, 3-90, 3-96, 3-99, 3-101,
3-159,4-1
II
field_extract, 3-11, 3-16, 3-38, 4-32
field_insert, 3-11, 3-16, 3-39, 4-32
fill_convex, 3-7, 3-8, 3-40, 8-2, 8-6
fill_oval, 3-7, 3-42, 8-2, 8-6
fillJ)iearc, 3-7, 3-43, 8-2, 8-6
fillJ)olygon, 3-7, 3-8, 3-44, 3-80, 3-174, 8-2,
8-6
filUect, 3-7,3-48,8-2,8-6
floating point, 2-6, 4-40, 4-41
floating point coprocessor. See coprocessor
flush_esym, 3-12, 3-49,4-32
flush_extended, 3-12, 3-50, 4-32
font, 2-13, 3-9, 3-26, 3-62, 3-95, 3-97, 3-140,
3-145,3-179,3-180, A-7
FONTINFO structure. See font
foreground color, 3-5, 3-55, 3-143, 3-145,
3-158,4-33
frame_oval, 3-7, 3-51, 8-2
frame_rect, 3-7, 3-52, 8-2
function_implemented, 3-3, 3-6, 3-20, 3-53,
3-69,3-70,8-9
°
II
ENVIRONMENT structure, 3-5, 3-61,3-145,
4-33, A-6
Index-2
get_colors, 3-5, 3-55
geCconfig, 3-3, 3-35, 3-57, 3-64, 3-90,
3-112,3-118,3-129,3-135,3-144,4-13,
4-16
geCcurs_state, 3-10, 3-59
geCcurs_xy, 3-10, 3-60
geCenv, 3-5, 3-61, 3-175
Index
geUontinfo, 3-9, 3-62
geUsr_priorities, 3-12, 3-63, 3-96, 3-101,
3-159,4-32,4-44,4-45
geCmodeinfo, 3-3, 3-57, 3-64, 3-144, 4-32,
A-11
geCnearest_color, 3-6, 3-65, 8-9
geCoffscreen_memory, 3-11,3-58,3-66,
3-174, A-12, A-14
getJ)alet, 3-6, 3-69,8-9
getJ)aleCentry, 3-6, 3-69, 3-70
getJ)ixel, 3-10,3-72
geCpmask, 3-5, 3-73, 3-164
getJ)pop, 3-5, 3-74, 3-164
geUextattr, 3-9, 3-75
geUransp, 3-5, 3-76
geCvector, 3-11 , 3-77
geCvideomode, 3-3, 3-78, 3-171, 4-32
get_windowing, 3-5, 3-79
geCwksp, 3-8, 3-44, 3-80
graphics manager, GM, 1-5,2-5,2-10,3-3,
3-8, 3-16, 3-24, 3-86, 3-96, 3-101, 4-14,
4-32,4-35,4-44,4-47,4-49
graphics output functions, 3-7, 8-2
graphics utility functions, 3-10
gsp_calloc, 3-11 , 3-85
gsp_execute, 3-3, 3-16, 3-86, 3-106
gsp_free, 3-11,3-87
gsp_malloc, 3-11, 3-66, 3-88, 3-162, 3-174
gsp_maxheap, 3-11, 3-89
gsp_minit, 3-11, 3-57, 3-90
gsp_realloc, 3-11,3-91
gsp2cop, 3-11,3-53, 3-81
gsp2gsp, 3-11,3-82
gsp2host, 3-11 , 3-16, 3-83, 4-32
gsp2hostxy, 3-11,3-16,3-84,4-32
m
host2gsp, 3-11 , 3-16, 3-92, 4-32
host2gspxy, 3-11 , 3-16, 3-93, 4-32
D
include files, 2-5, 2-8, 2-9, 2-18, 4-11,4-14,
4-32, 4-43, A-1
initJ)alet, 3-6, 3-53, 3-94,8-10
iniUext, 3-9, 3-95
initialization, 2-10, 3-3, 3-90, 3-94, 3-95,
3-145,4-46,4-49
install_aim, 3-12, 3-63, 3-96, 3-159, 4-3, 4-9,
4-11,4-32,4-43,4-47
install_font, 3-9, 3-95, 3-97
installJ)rimitives, 3-3, 3-12, 3-99, 4-10, 4-32
install_rim, 3-12, 3-24, 3-63, 3-101, 3-159,
4-3,4-7,4-11,4-32,4-38,4-45,4-47
install_usererror, 3-3, 3-4, 3-35, 3-41 , 3-45,
3-103,3-113,3-119,3-129,3-135,3-168,
3-171,4-32
installation, 2-4, 4-7, 4-38, 4-44
interrupt, 2-6, 2-11, 3-12, 3-63, 3-79, 3-96,
3-101,3-159, 3-173, 4-2, 4-4, 4-5, 4-32,
4-33,4-35,4-44,4-45,4-46
II
Iib,2-17
link,2-17
linking loader, 1-5,2-10,3-22,3-24,3-49,
4-1,4-2,4-9,4-47
Imo, 3-10, 3-105
loadcoff, 3-3, 3-16, 3-86, 3-106
II
make, 2-6, 2-12, 2-17, 4-38
math/graphics, 1-2, 2-12, 2-13
memory management, 3-2, 3-11, 4-2, A-3
mg2tiga utility, 2-13
MODEINFO structure, 3-3, 3-57, 3-64,
3-144, A-11
MONITORINFO structure, A-13
Index-3
m
num_modes, 3-57, A-3
pen, 3-6, 3-7, 3-61, 3-123, 3-126, 3-127,
3-128,3-129,3-131,3-132,3-133,3-134,
3-135, 3-145, 3-163, A-6, 8-2, 8-8
num_offscr!1_areas, 3-58, 3-66, A-12
numJ)ages, 3-58, 3-108, A-12
m
offscreen, 3-4, 3-18, 3-19, 4-33, A-12, A-14
iii
page, 3-4, 3-10, 3-18, 3-58, 3-107, 3-108,
3-144,4-33, A-12
PAGE structure, A-15
page_bus~3-10,3-107
page_flip, 3-10, 3-108, A-15
PALET structure, A-16
palet-1)un_depth, 3-6, 3-58, A-11, 8-9
paleUnset, 3-58, A-12
paleCsize, 3-58, 3-69, A-12
palette, 3-6, 3-18, 3-65, 3-69, 3-70, 3-94,
3-160,3-161, A-11, A-16, 8-9
patnfill_convex, 3-7, 3-8, 3-112,8-2,8-4,8-6
patnfill_oval, 3-7, 3-114,8-2,8-4,8-6
patnfillJ)iearc, 3-7, 3-115,8-2,8-4,8-6
patnfillJ)olygon, 3-7, 3-8, 3-118, 8-2, 8-4,
8-6
patnfilUect, 3-7, 3-120,8-2,8-4,8-6
patnframe_oval, 3-7, 3-121,8-2,8-4
patnframe_rect, 3-7, 3-122, 8-2, 8-4
patnpen_line, 3-7, 3-123, 8-2, 8-4, 8-8
patnpen_ovalarc, 3-7, 3-126, 8-2, 8-4, 8-8
patnpen_piearc, 3-7, 3-127, 8-2, 8-4, 8-8
patnpen_point, 3-128, 8-2, 8-4, 8-8
patnpenJ)olyline, 3-7, 3-8,3-129,8-2,8-4,
8-8
pattern, 3-5, 3-6, 3-7, 3-61, 3-112, 3-114,
3-115,3-118,3-120, 3-121,3-122,3-123,
3-126,3-127,3-128,3-129,3-139,3-145,
3-162,4-33, A-6, A-17, 8-2, 8-4
PATTERN structure. See pattern
peek_breg, 3-10, 3-130
Index-4
pen_ovalarc, 3-7, 3-132, 8-2, 8-8
penJ)iearc, 3-7, 3-133,8-2,8-8
pen_point, 3-7, 3-134,8-2,8-8
penJ)olyline, 3-7, 3-8, 3-135, 8-2, 8-8
pixel array function, 3-8
pixel mask, 3-58, A-11
pixel processing, 3-5, 3-74, 3-76, 3-145,
3-146,3-165, A-5
plane mask, 3-5, 3-73, 3-145, 3-164
poke_breg, 3-10, 3-136
poly drawing functions, 3-8, 4-16, 8-2, 8-6,
8-8
porting TIGA, 0-1
program_mem_end, 3-57, A-3
program_mem_start, 3-57, A-3
m
register usage, 4-33
relocatable load module, RLM, 3-22, 3-101,
4-2,4-5,4-38,4-48,4-49
installation, 4-7
rmo, 3-10, 3-137
II
screen_high, 3-58, A-11
screen_wide, 3-58, A-11
seed_fill, 3-7, 3-66, 3-138
seedJ)atnfill, 3-7, 3-139
select_font, 3-9, 3-140
seCbcolor, 3-5, 3-141
seCclip_rect, 3-5, 3-14, 3-142
seCcolors, 3-5, 3-143
seCconfig, 3-3, 3-144, 4-32, A-3
seCcurs_shape, 3-10, 3-90, 3-146, A-5
seCcurs_state, 3-10, 3-152
seCcurs_xy, 3-10, 3-146, 3-153, A-5
seCdraw_origin, 3-5, 3-61, 3-154, A-6, 8-5
seCdstbm, 3-8, 3-14, 3-61, 3-155, A-6
seCfcolor, 3-5, 3-158, A-7
Index
seUnterrupt, 3-12, 3-159, 4-44, 4-45
setJlalet, 3-6, 3-53, 3-69, 3-160,8-9
setJlalet_entry, 3-6, 3-53, 3-69, 3-161,8-9
setJlatn, 3-5, 3-162, A-17
See also pattern
seCpensize, 3-5, 3-123, 3-163, A-6
See also pen
setJlmask, 3-5, 3-73, 3-164
setJlPop, 3-5, 3-74, 3-165
seCsrcbm, 3-8, 3-14, 3-61, 3-166, 3-184,
A-6
seUextattr, 3-9, 3-167, 3-179, A-1 0
seUimeout, 3-3, 3-4, 3-168, 4-32
seUransp, 3-5, 3-53, 3-169, 3-181, 3-182
set_vector, 3-11 , 3-170
seCvideomode, 2-10, 3-3, 3-16, 3-78, 3-145,
3-171,4-32,4-38,4-43
seCwindowing, 3-5, 3-79, 3-173
seCwksp, 3-8, 3-44, 3-66, 3-80, 3-90, 3-118,
3-174
share_gsp_addr, 3-57, A-4
share_hoscaddr, 3-57, A-4
share_mem_size, 3-57, A-4
software developer's kit, SDK, 1-2
software porting kit, SPK, 1-2, 2-4
subdirectories, 2-5
system requirements, 2-2
stack_size, 3-57, 3-90, A-4
styled_line, 3-7, 3-61,3-175, A-6
swap_bm, 3-8, 3-177
symbol table, 3-12, 3-24, 3-49, 3-50, 4-2,
4-48,4-49
synchronize, 3-3, 3-4, 3-178, 4-32, 4-40
syntax and programming examples, 2-18
sys_flags, 3-20, 3-57, 3-81, A-3
system requirements, 2-2
II
text, 2-13, 3-9, 3-26, 3-62, 3-75, 3-95, 3-97,
3-140,3-167,3-179,3-180,4-33, A-7
texCout, 3-9, 3-167, 3-179
texCwidth, 3-9, 3-167, 3-180
TIGAEXT section, 3-96, 3-101, 4-4, 4-5,
4-11,4-13,4-38,4-39,4-45,4-47
TIGAISR section, 4-4,4-5,4-44,4-45,4-47
TIGALNK, 1-5,2-10,3-22,3-24,3-49,4-1,
4-2,4-9,4-47
TIGAMODE utility, 2-6, 2-16, 3-3
transp_off, 3-5, 3-181
transp_on, 3-5, 3-182
transparency, 3-5, 3-53, 3-76, 3-145, 3-169,
3-181,3-182,4-33
trap vector, 3-11 , 3-77, 3-170
m
utilities, 2-5, 2-12, 2-17, 3-3, 3-10
version_number, 3-57, A-3
waiCscan, 3-10, 3-183
windowing, 3-6, 3-79, 3-142, 3-145, 3-173
wksp_addr, 3-58, 3-80,3-174, A-12
wksPJlitch, 3-58, 3-80, 3-174, A-12
workspace, 3-8, 3-44, 3-58, 3-66, 3-80,
3-118,3-174
zoom_rect, 3-8, 3-66, 3-184
Index-5
Index
Index-6
TI Sales Offices TI Distributors
ALABAMA: Hunlsvtllo (205) 837-7530_
ARIZONA: Phoenix (602) 995-1007;
Tucson (602) 292-2640.
CALIFORNIA: Irvine (114) 660-1200;
Roseville (916) 786·9208;
San Diego (619) 278·9601;
Santa Clara (408) 980-9000;
Torrance (213) 217·7010;
Woodland Hills (818) 104·7759.
COLORADO: Aurora (303) 368-8000_
CONNECTICUT: Wallingford (203) 269-0074FLORIDA: Altamonte Springs (305) 260-2116;
Ft. Lauderdale (305) 973-8502j
Tampa (813) 885--7411.
GEORGIA: Norcross (404) 662·7900.
ILLINOIS: Arlington Heights (312) 640-2925.
INDIANA: Carmel (317) 573-6400j
Ft. Wayne (219) 424-5174.
IOWA: Cedar Rapids (319) 395-9550.
TI AUTHORIZED DISTRIBUTORS
Arrow/Klerulff Electronics Group
Arrow (Canada)
Future Electronics (Canada)
GRS Electronics Co., Inc_
Hall-Mark Electronics
Marshall Industries
Newark Electronics
Schweber Electronics
Time Electronics
Wyle Laboratories
Zeus Components
-OBSOLETE PRODUCT ONLYRochester Electronics, Inc_
Newburyport, Massachusetts
(508) 462-9332
KANSAS: Overland Park (913) 451·4511.
MARYLAND: Columbia (301) 964·2003.
MASSACHUSETTS: Wattham (617) 895-9100.
MICHIGAN: Farmington Hills (313) 553-1569;
Grand Rapids (616) 957-4200.
MINNESOTA: Eden Prllirle (612) 828-9300.
MISSOURI: SI. Louis (314) 569-7600_
NEW JERSEY: Isolln (201) 750-1050_
NEW MEXICO: Albuquerque (505) 345-2555.
NEW YORK: East Syracuse (315) 463-9291;
Melville (516) 454-6600;
Pittsford (716) 385-6770;
Poughkeepsie (914) 473-2900.
NORTH CAROLINA: Charlotte (704) 527-0933;
Raleigh (919) 876-2725.
OHIO: Beachwood (216) 464-6100;
Beaver Creek (513) 427-6200.
OREGON: Beaverton (503) 643-6758_
PENNSYLVANIA: BI.o Boll (215) 825-9500_
PUERTO RICO: Halo Rey (809) 753-8700_
TENNESSEE: Johnson City (615) 461-2192_
TEXAS: Austin (512) 250-7655;
Houston (713) 778-6592:
Richardson (214) 680-5082;
San Antonio (512) 496-1779.
UTAH: Murray (801) 266-8972.
WASHINGTON: Rodmond (206) 881-3080_
WISCONSIN: Brookfield (414) 782-2899.
CANADA: Nepean. Ontario (613) 726-1970j
Richmond Hili, OntarIo (416) 884-9181i
St_ Laurent, Quebec: (514) 33&-1860.
TI Regional
Technology Centers
CALIFORNIA: Irvlno (714) 660-8105;
Santa Clara (408) 748-2220:
GEORGIA: Norcross (404) 662-7945.
ILLINOIS Arlington Heights (312) 64()'2909.
MASSACHUSETTS: Waltham (617) 895-9196_
ALABAMA: Arfow/Kierulff (205) 837-6955;
Halt-Mark (205) 837~8700; Marshall (205) 881·9235;
Schweber (205) 895-0480.
ARIZONA: Arrow/Kierulff (602) 437·0750;
Halt-Mark (602) 437·1200; Marshall (602) 496-0290;
Schweber (602) 431-0030; Wyle (602) 866-2888.
CALIFORNIA: Los Angeles/Orange County:
ArrowiKierulff (818) 701·7500, (714) 838·5422;
Hall-Mark (818) 773-4500. (714) 669-4100;
Marshall (818) 407·0101, (818) 459-5500.
(714) 458-5395; Schweber (818) 880-9686;
(714) 863-0200, (213) 320-8090; Wyle (818) 880·9000,
~lt1c418~~~;~~3~;,r.~a~~1~1~~~~~~8(~;18) 889-3838;
Marshall (916) 635-9700; Schweber (916) 364-0222;
Wyle (916) 638-5282;
San Diego: Arrow/Kierulff (619) 565-4800;
Hall-Mark (619) 268-1201; Marshall (619) 578·9600;
Schweber (619) 450·0454; Wyle (619) 565-9171;
San Francisco Bay Area: Arrow/Kierulff (408) 745-6600,
Hall-Mark (408) 432-0900; Marshall (408) 942-4600;
Schweber (408) 432-7171: Wyle (408) 727-2500:
Zeus (408) 998-5121.
COLORADO: Arrow/Kterultf (303) 790-4444;
Hall-Mark (303) 790-1662; Marshall (303) 451-8383:
Schweber (303) 799-0258; Wyle (303) 457-9953.
CONNETICUT: ArrowlKierulff (203) 265-7741;
Hall-Mark (203) 271-2844; Marshall (203) 265-3822;
Schweber (203) 264-4700.
FLORIDA: Ft. Lauderdale:
Arrow/Kierultf (305) 429-8200; Hall·Mark (305) 971-9280:
Marshall (305) 977-4880; Schweber (305) 977-7511;
OrlandO: ArrowiKierulff (407) 323-0252,
Hall.Mark (407) 830-5855; Marshall (407) 767-8585:
Schweber (407) 331-7555; Zeus (407) 365-3000;
Tampa: Hall·Mark (813) 530-4543;
Marshall (813) 576-1399; Schweber (813) 541·5100.
GEORGIA: Arrow/Kierulff (404) 449-8252;
Hall-Meork (404) 447-8000; MarshaH (404) 923-5750;
Schweber (404) 449-9170.
ILLINOIS: ArrowlKierulff (312) 250-0500;
Hall-Mark (312) 860-3800; Marshall (312) 490-0155;
Newark (312) 784-5100; Schweber (312) 364·3750.
INDIANA: Indianapolis: ArrowlKlerulff (317) 243-9353;
Hall-Mark (317) 872-8875; M,srshall (3l7) 297-0483i
Schweber (317) 843·1050. -,
IOWA: ArrowlKierulff (319) 395-7230i
Schweber (319) 373-1417.
KANSAS: KansasClty: Arrow/Kierulff(913)541·9542;
Hall-Mark (913) 888-4747; Marshall (913) 492-3121;
Schweber (913) 492·2922.
MARYLAND: Arrow/Klerulll (301) 995-8002;
Hall-Mark (301) 988-9800; Mars"all (301) 235-9464;
Schwebur (301) 840-5900; Zeus (301) 997-1118.
MASSACHUSETTS Arrow/KlerulH (508) 658-0900;
Hall·Mark (508) 667-0902; Marshall (508) 658-0810i
Schweber (617) 275·5100; TIme (617) 532·6200;
Wyle (617) 273-7300; Zeus (617) 863-8800.
MICHIGAN: Detroit: Arrow/Klerulff (313) 462-2290;
Hall-Mark (313) 462-1205; Marshall (313) 525-5850;
Newark (313) 967-0600; Schweber (313) 525-8100;
Grand Rapids: Arrow/Klerulff (616) 243·0912.
~~~_~~~~~~~t;~~~~J~~u~~~~~;t,1~~1~~O~_2211 ;
Schweber (612) 941-5280.
MISSOURI: SI. louis: Arrow/Kierulff (314) 567-6888;
Hall-Mark (314) 291-5350; Marshall (314) 291-4650;
Schweber (314) 739-0526.
NEW HAMPSHIRE: Arrow/Kierulff (603) 668-6968;
Schweber (603) 625-2250.
NEW JERSEY: Arrow/Klerulff (201) 538-0900.
(609) 596-8000; GRS ElectronIcs (609) 964-8560;
Hall-Mark (201) 575-4415, (201) 882-9773.
(609) 235-1900; Marshall (201) 882-0320,
(609) 234-911)0; Schweber (201) 227~7880.
NEW MEXICO: Arrow/Kierulff (505) 243--4566.
NEW YORK: Long Island:
Arrow/Kierulff (516) 231-1009; Hall·Mark (516) 737-0600;
Marshall (516) 273-2424; Schweber (516) 334-7474;
Zeus (914) 937-7400;
Rochester: Arrow/Kierulff (716) 427·0300;
Hall-Mark (716) 425·3300; Marshall (716) 235-7620;
Schweber (716) 424-2222;
Syracuse: Marshall (607) 798·1611.
NORTH CAROLINA: ArrowlKierulff (919) 876-3132,
(919) 725·8711; Hall-Mark (919) 872·0712;
Marshall (919) 878-9882; Schweber (919) 876-0000.
OHIO: Cleveland: Arrow/KlerulH (216) 248·3990;
Hall·Ma~k (216) 349-4632; Marshall (216) 248-1788;
Schweber (216) 464-2970;
Columbus: Hall-Mark (614) 888·3313;
Dayton: ArrowiKierulff (513) 435-5563;
Marshall (513) 898-4480; Schweber (513) 439-1800.
OKLAHOMA: Arrow/Kierulff (918) 252-7537;
Schweber (918) 622-8003.
OREGON: ArrowlKierulff (503) 645-6456;
Marshall (503) 644-5050; Wyle (503) 640-6000.
PENNSYLVANIA: Arrow/Kierulff (412) 856-7000.
(215~ 928·1800; GRS Electronics (215) 922·7037;
Marshall (412) 963-0441; Schweber (215) 441·0600,
(412) 963-6804.
TEXAS: Austin: Arrow/Kieruiff (512) 835-4180;
Hall·Mark (512) 258-8848; Marshall (512) 837-1991i
Schweber (512) 339-0088; Wyle (512) 834·9957;
Dallas: AtrowlKierulff (214) 380-6464;
Hall-Mark (214) 553-4300; Marshall (214) 233-5200;
Schweber (214) 661-5010; Wyle (214) 235·9953i
Zeus (214) 783-7010;
EI Paso: Marshall (915) 593-0706;
Houston: Arrow/Kierutff (713) 530·4700;
Halt-Mark (713) 781-6100; Marshall (713) 895-9200;
Schweber (713) 784·3600; Wyle (713) 879-9953.
UTAH: ArrowiKieruiff (801) 973-6913;
H!lII-Mark (801) 972-1008; Marshall (801) 485-1551;
Wyle (801) 974-9953.
WASHINGTON: Arrow/Klerulff (206) 575-4420;
Marshall (206) 486-5747; Wyle (206) 881-1150.
WISCONSIN: Arrow/Kierulff (414) 792-0150;
Hall-Mark (414) 797·7844; Marshall (414) 797-8400;
Schweber (414) 784·9020.
CANADA: Calgary: Future (403) 235-5325;
Edmonton: Future (403) 438-285e;
Montreal: Arrow Canada (514) 735-5511;
Future (514) 694-7710;
Ottawa: Arrow Canada (613) 226-6903;
Future (613) 820-8313;
Quebec City: Arrow Canada (418) 871-7500;
Toronto: Arrow Canada (416) 672·7769;
Future (416) 638-4771; Marshall (416) 674.2161;
Vancouver: Arrow Canada (604) 291-2986;
Future (604) 294-1166.
TEXAS: Rlchzlrdson (214) 68G-5066.
CANADA: Nepean, Ontario (613) 728-1970_
Customer
Response Center
TEXAS
INSTRUMENTS
TOLL FREE: (800) 232-3200
OUTSIDE USA: (214) 995-6611
(8,00 a_m_ - 5,00 p.m_ CST)
A-la9
TI Worldwide
Sales Offices
~=:A~"!t=: (~;'1!~,;vra::SuIte BI4-
:n~:i.=8r~&~;~~·8nw.(~iroele
Mile. Suite 43. Tucaon. AZ 85705. (8021 282·2840.
~1~i2~9.:.=~~e:;i=' CA
PI.... Rooovlll•• CA 85678. (8161 786-8208;
:: g-o: 4333 ~ ~~\~ ~;;:9~~~ 100.
=-
=~(l'r~:~'K~~'St~
OREGON: _ : 8700 SW 105th St•.-Sullo 110.
ee.....on, OR 8700B. (6031 843-8758.
~~~~~~~!~! ~~~.~;;r PkWY.
~~~:~0,=.'l;:'::ic3."l'J~z:5':e"700.
TENNESSEE: _ _ CIty: Erwin Hwy.
P.O. Draw.. 1255. Johnoon City, TN 37805
(6151461-2192.
TEXAS: Aullln: 12601 _rch Blvd .. AUllln, TX
78759, (5121 250·7855; 11_ _ : 1001 E.
Campbell Rd., Richord..n, TX 75081,
12141680-5082; HOUlton: 9100 Southwest Frwy.•
Suite 250. Houston. TX 77074, (7131 778·6592;
:::
=~ l~~~r1~~~jk::l.f:~·
UTAH: - . , : 5201 South Groen St•• Suite 200.
Mutroy,
ur 84123, (8011266-8972.
r!.~~;"'='=::.::1~2~1~t1f81'!'~.
=
IfONG KONG: T.... "'.........,. ~Kono Ltd.....
::,~? 1~~?7gri2~3~~
.• Kowloon.
IRElAND: Texas Instrument. flreland) Umhed:
f/~8~'g~rt Street. Stillorgln. County DubNn.
En.
ITALY: Texas Instruments Italla S.p.A. DiVisione
Semie:onduttori: Viele Europa. 40. 20093 Cologne
Monzese (Milano). (02) 263001; Via Castello della
Maglian•• 38.00148 Rome. 106) 5222851;
Vi. Amendol•• 17.40100 8oIognl, (0511554004JAPAN: Tokvo Martc.eting/Salas IHeadquarters):
Japan Ltd •• M5 Shibaura Bldg•• 9F.
aura. Minato-ku. Tokyo 108. J'I)ItI.
. Tex.. Instruments Japan Ltd.: NillhoI
• 30 Imabashi 3-chome. Higashi-ku.
g~:a7r~tilrM'e:=i~~~~itP:~~!~~r:. Wnt
Nagova 450. 052·583·8691; Daiichi Selmai BkIg. 8F.
3-10 Oyama-coo. Kanazawa 920. Ishikawa-ken.
0782-23-5471; Daiichi Otvm' Tachikawa Bidg. 8F.
'-2S.12 Akebono-cho. Tae
Torrence.
602. (2131217·7010;
_ _ : 21220 Erwin 5... Wooclend Hillo.
CA 81387. (8181 704-7758.
COLOllADQ: _ : 1400 S. PoIomoe A....
WISCONSIN: _ : 460 N. Sunny 51_, Suite
150. B 368-8000.
CANADA: N. . . .: 301 Moodie Drive. MBItom Center.
0263-33·1080; Yokoho
2-8-4 Kita·Saiwai·eho. Nishi-ku
hama 2 O.
045-322-6741; Nihon Slrimel Kyoto Vasaka Bldg. SF.
(6131726·1970. _
HIlI: 280 Cantr. 5 •. E..
Richmond Hili L4C1Bl. Ont.",. Canada
(4181884·9181; S•• Lou_: ViH.S•. l.aufent
2597-1. Aza Harudai. Oaza Vasaka. Kltsuki 873. Oha-
CONNECTICUT: W.....-: 8 1IIrne. Induotrill _
..
2t·O:;~ ('=r~:~~~4~
tingford.
R.ORIOA: AIIo_
8:=: r.~!r~~~1~;1~i~'3:'\8't8~ent.
:.~~~nj,
F•. Lauderdale. FL
~=: ~~~~Mm'J~~M~'
==
Nep••n, Ontario, Canada, K2H9C4.
602;.
:,.o=2.~em~peIdlno Drive. Norcroee.
ARGENTINA: Tex•• Instruments Argenttna Vi,monte
U~~4~~~:9~aPital Federat, Buenos Aires. Argentina.
AUSTRAUA (. NEW ZEALANDI:
re•••
In.tru......
Australia Ltd.: 6·10 Talavera Rd .• North Ryde
=~~\=~. ~~~2~8:~rs~'t'·
g~;'.~,:~~i;~un 300·04. lbaragi-ktn.
KOREA: Texas Instruments Korea ltd•• 28th Fl.. Trade
~~::r2~':1i_~;16.'g-Dong. Kangnam·ku. Seout.
MEXICO:·Texas Instrument. de Mexico 5.A.: Atfonso
Reyes-115. Col. Hlpodromo Condela, Mexteo. D.F••
M••ico 08120,525/525·3880.
MIDDLE EAST: Texas Instruments: No. 13. lit Floor
Mannai Bldg .• Diplomatic Area. P.O. 80. 26335.
AUSTRIA: Taxa. Instruments Ges.m.b.H.:
HoII.nd 20 + 5802911.
_NA: Ft. Wevno: 2020 Inwood Dr..
Dr..
Melbourne. V;ctoria. Australia 3004.3 +- ~67-4817;
~7J ~g~2~:.W'V. Elizabeth. South AUltrl!ia 5112.
IOWA: Cedlrlllp/dl: 373 Conins Ad. NE. Suite 201.
Ceder Rapid•• (A 52402. (3181385-8560.
f3N,-tge.:2~~ 8/16. A-2345 Brunn/Gtbirge,
Manama Bahrain. Arabian Gulf. 973+274681.
NETHERLANDS: Texas Instruments Holland B.V.,
19 Hogehilweg. 1100 AZ Amsterdam-Zuidoost.
=.~.;.~~J:Wo~~~ :f~~,'f'""
Dr..
MARYLANO: ~: 8815 Ce.... ""ric
Columbi. MD 21045. (3011 864-2003.
MA68ACHUSETTS: W _ : 860 WInter St..
W.~h.m, MA 02154. (8171895·8100.
BELGIUM: Taxa Instruments N.V. Belgium S.A.: '11.
~2r~t~~~et an 11. 1140 Brussels. Belgium.
..
BRAZIL: Texas Instruments Electronlcos do BralU
Ltda.: Rua Pees Leme. 524-7 And. PinheirOl. 05424
Sao Paulo. Brazil. 0815-6166.
~::r::tr':'80~:(mm::,~~:'iIt Ad••
...........: 3075 Orchard Vilta Dr. S.£ .•
Grend Rapidl. MI48508. (6161857·4200.
MINNESOTA: EdIn _ : 11000 W. 78111 St..
Eden Prairi•• MN 55344 (8121 826-9300.
MISSOURI: St. ~: 11818 Ilo
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Create Date : 2017:08:01 12:11:11-08:00
Modify Date : 2017:08:01 13:19:59-07:00
Metadata Date : 2017:08:01 13:19:59-07:00
Producer : Adobe Acrobat 9.0 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:560306f3-6bb1-1c44-925d-7dda8cf5306f
Instance ID : uuid:45afdb6d-e242-6649-bfae-497f41b387fb
Page Layout : SinglePage
Page Mode : UseNone
Page Count : 374
EXIF Metadata provided by EXIF.tools