 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| Interface User's Guide September 1990 Computer Video Products Interface User's Guide SPVU015C September 1990 Printed on Recycled Paper 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 TI'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 of TI covering or relating to any combination, machine, or process in which such semiconductor products or services might be or are used. Texas Instruments products are not intended for use in life-support appliances, devices, or systems. Use of a TI product in such applications without the written consent of the appropriate TI officer is prohibited. Copyright (c) 1991, Texas Instruments Incorporated Preface Read This First How to Use This Manual This document contains the following chapters: Chapter 1 Chapter 2 Introduction Introduces the TIGA Interface, its features and architecture. Getting Started Contains instructions to install TIGA on a PC and to run a demonstration program. Application Interface Describes the application interface and lists all TIGA functions by functional group. Core Functions Describes the core functions alphabetically, showing the syntax and arguments of each function, a detailed description, and programming examples or references to related functions. Extended Graphics Library Functions Describes the extended functions contained in the TIGA graphics library, showing the syntax and arguments of each function, a detailed description, and programming examples or references to related functions. Graphics Library Conventions Describes the assumptions made and conventions adopted regarding coordinate systems, mapping of pixels to coordinates, operations on pixels, clipping, and the geometric figures and rendering styles supported by TIGA. Bit-Mapped Text Describes the text capabilities of TIGA, the types of fonts supported, and the internal structure of the database for each font; gives an alphabetical listing of the available fonts with illustrations. Extensibility Describes how to extend TIGA by adding your own functions; also describes the command processing entry points of the communication driver. Chapter 3 Chapter 4 Chapter 5 Chapter 6 Chapter 7 Chapter 8 iii How to Use This Manual/Related Documentation Appendix A Appendix B Appendix C Appendix D Appendix E Data Structures Describes the data structures used in TIGA. TIGA Reserved Symbols Describes the function names reserved for internal use of TIGA. Debugger Support for TIGA Describes TIGA debugger support functions. Error Messages / Error Codes Contains a list of error codes and messages returned by TIGA. Glossary Contains the definitions of TIGA-specific and TIGA-related terms and acronyms. Related Documentation The following documents are available from Texas Instruments: TMS34010 User's Guide (literature number SPVU001). Describes the internal architecture, hardware interfaces, programmable registers, and instruction set of the TMS34010 32-bit graphics processor chip. TMS34020 User's Guide (literature number SPVU019). Describes the internal architecture, hardware interfaces, programmable registers, and instruction set of the TMS34020 32-bit graphics processor chip. TMS340 Family Code Generation Tools User's Guide (literature number SPVU020). Describes the C compiler, assembler, linker, and archiver for the TMS340x0 graphics system processors. To obtain any of TI's product literature listed above, please contact the Texas Instruments Customer Response Center at toll-free telephone number (800) 336-5236, or at (214) 995-6611 if you are calling from outside the US and Canada. iv Read This First Related Documentation/Style and Symbol Conventions You may also find the following documentation useful: Kernighan, Brian, and Dennis Ritchie. The C Programming Language. Second Edition. Englewood Cliffs, New Jersey: Prentice-Hall, 1988. Kochan, Stephen G. Programming in C. Hasbrouck Heights, New Jersey: Hayden Book Company, 1983. Sobelman, Gerald E., and David E. Krekelberg. Advanced C: Techniques and Applications. Indianapolis, Indiana: Que Corporation, 1985. Style and Symbol Conventions This document uses the following conventions: TIGA functions and their parameters are shown in italic face in regular text. For example, the TIGA function draw_line has parameters x1, y1, x2, y2. Filenames (example: tigalnk.exe) are also shown in italic face.. Program examples and interactive display examples are shown in monospaced program font. Here is an example program: #include */ */ */ */ */ */ v Style and Symbol Conventions /*-------------------------------------------------------- /* Terminate TIGA /*-------------------------------------------------------- exit_tiga(); } exit_tiga() { set_videomode(PREVIOUS, INIT); tiga_set(CD_CLOSE); exit(0); } */ */ */ In syntax descriptions, the instruction, command, or directive is in a bold face font with parameters in italic face. Portions of a syntax in bold face (including quote marks) should be entered as shown. Portions of a syntax in italic face describe the type of information that you provide. Square brackets identify optional information: mg2tiga MG font TIGA font [ "facename" ] Italic face is also used to emphasize a word or phrase that may be important or that is being defined or used for the first time in a chapter. vi Read This First Trademarks Trademarks DGIS is a trademark of Graphic Software Systems, Inc. GEM is a trademark of Digital Research, Inc. GSS*CGI is a trademark of Graphic Software Systems, Inc. High C and Metaware are trademarks of MetaWare Incorporated. MS-Windows, PM, MS-DOS, and CodeView are trademarks of Microsoft Corp. NDP C-386 and MicroWay are trademarks of Microway, Inc. Phar Lap, 386|DOS-Extender, and 386|VMM are trademarks of Phar Lap Software, Inc. PC-DOS and PGA are trademarks of IBM Corp. TIGA is a trademark of Texas Instruments Incorporated. vii viii Read This First Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 1-2 1-3 1-5 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 2.1 TMS340 Development Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 2.2 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.2.1 TIGA Driver Development Package (TIGA-DDP) and TIGA Software Development Package (TIGA-SDP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.2.2 TIGA Software Porting Package (TIGA-SPP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.3 Installing TIGA on Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.3.1 TIGA Driver Development Package (TIGA-DDP) Subdirectories . . . . . . . . . . . 2-5 2.3.2 TIGA Software Development Package (TIGA-SDP) Subdirectories . . . . . . . . . 2-5 2.3.3 TIGA Software Porting Package (TIGA-SPP) Subdirectories . . . . . . . . . . . . . . 2-5 2.4 Modifying Autoexec and the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 2.5 The TIGA Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 2.6 Running the TIGA Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 2.7 TIGA Utility Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 2.7.1 cltiga Batch File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 2.7.2 mg2tiga Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 2.8 Rebuilding Existing TIGA Applications for TIGA 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 2.8.1 TIGA 2.0 Initialization / Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 2.8.2 CURSOR Structure Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 2.8.3 Return Value of set_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 2.8.4 Elimination of Offscreen Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 2.8.5 TIGA 1.1 Functions No Longer Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 2.8.6 New Functions Available in TIGA 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 2.8.7 Functional Differences in TIGA 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 Application Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Supported Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1 Host-PC Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2 TMS340 Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Host-PC Include Files and Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 TMS340 Include Files and Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 3-2 3-2 3-2 3-3 3-5 3 ix Contents 3.4 3.5 3.6 Sample TIGA Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 TIGA Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 3.5.1 Core Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 3.5.2 Extended Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Summary of Functions by Functional Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 3.6.1 Graphics System Initialization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 3.6.2 Clear Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 3.6.3 Graphics Attribute Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 3.6.4 Palette Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 3.6.5 Graphics Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 3.6.6 Poly Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13 3.6.7 Pixel Array Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 3.6.8 Text Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 3.6.9 Graphics Cursor Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 3.6.10 Graphics Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16 3.6.11 Handle-Based Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . 3-16 3.6.12 Pointer-Based Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . 3-17 3.6.13 Data Input/Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 3.6.14 Extensibility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 3.6.15 Interrupt Handler Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 4 5 6 Core Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 4.1 Core Functions Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Extended Graphics Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 5.1 Extended Graphics Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Graphics Library Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 6.1 Graphics Library Function Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 6.2 Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 6.3 Area-Filling Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 6.4 Vector-Drawing Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 6.5 Rectangular Drawing Pen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 6.6 Area-Fill Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 6.7 Line-Style Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13 6.8 Operations on Pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15 6.8.1 Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15 6.8.2 Plane Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16 6.8.3 Pixel-Processing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16 6.9 Clipping Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18 6.10 Pixel-Size Independence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19 Bit-Mapped Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 7.1 Bit-Mapped Font Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 7.2 Font Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 Table of Contents 7 x Contents 7.3 7.4 7.5 7.6 7.2.1 Font Header Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 7.2.2 Font Pattern Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8 7.2.3 Location Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 7.2.4 Offset/Width Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 Proportionally Spaced Versus Block Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11 Font Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12 Text Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13 Available Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 7.6.1 Installing Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15 7.6.2 Alphabetical Listing of Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16 8 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 8.1 Dynamic Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 8.1.1 Relocatable Load Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 8.1.2 Absolute Load Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 8.2 Generating a Dynamic Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 8.2.1 TIGAEXT Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 8.2.2 The TIGAISR Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 8.2.3 Linking the Code and Special Sections Into an RLM . . . . . . . . . . . . . . . . . . . . . 8-5 8.3 Installing a Dynamic Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6 8.3.1 Installing a Relocatable Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6 8.3.2 Installing an Absolute Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 8.4 Invoking Functions in a Dynamic Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 8.4.1 Command Number Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 8.4.2 Using Macros in Command Number Definitions . . . . . . . . . . . . . . . . . . . . . . . . 8-10 8.4.3 Passing Parameters to the TIGA Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10 8.5 C-Packet Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12 8.5.1 The Type of Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12 8.5.2 The Command Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12 8.5.3 Description of Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13 8.5.4 C-Packet Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14 8.5.5 Overflow of the Command Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15 8.6 Direct Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16 8.6.1 Differences Between Microsoft C and High C/NDP Compilers . . . . . . . . . . . . 8-16 8.6.2 Standard Command Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17 8.6.3 Standard Command Entry Point With Return . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18 8.6.4 Standard Memory Send Command Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . 8-19 8.6.5 Standard Memory Return Command Entry Point . . . . . . . . . . . . . . . . . . . . . . . . 8-20 8.6.6 Standard String Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21 8.6.7 Altered Memory Return Command Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . 8-21 8.6.8 Send/Return Memory Command Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21 8.6.9 Mixed Immediate and Pointer Command Entry Point . . . . . . . . . . . . . . . . . . . . 8-22 8.6.10 Mixed Immediate and Pointer Command Entry Point With Return . . . . . . . . . 8-22 8.6.11 Poly Function Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22 xi Contents 8.7 8.8 8.9 8.10 8.11 8.6.12 Immediate and Poly Data Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloaded Function Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.7.1 Register Usage Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.7.2 TIGA Graphics Manager System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . Using the TMS340-to-Host Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.1 The Command Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.2 Description of the Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.3 Call-Back Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.4 Initializing the Callback Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.5 Sizing the Callback Buffer and Handling Overflow . . . . . . . . . . . . . . . . . . . . . . . Installing Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Code Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.1 Determining the Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.2 Pattern B-File Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.3 Pitch Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.4 Video Timing Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.5 TM34020-Specific Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.6 VRAM Block Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TIGA Linking Loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11.1 /ca - Create Absolute Load Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11.2 /cs - Create External Symbol Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11.3 /ec - Error Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11.4 /fs - Flush External Symbol Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11.5 /la - Load and Install an Absolute Load Module . . . . . . . . . . . . . . . . . . . . . . . . 8.11.6 /lr - Load and Install a Relocatable Load Module . . . . . . . . . . . . . . . . . . . . . . . 8.11.7 /lx - Load and Execute a COFF File / Execute TIGA GM . . . . . . . . . . . . . . . . 8-25 8-28 8-29 8-30 8-31 8-31 8-31 8-32 8-33 8-34 8-36 8-39 8-39 8-40 8-40 8-41 8-43 8-43 8-45 8-45 8-46 8-46 8-47 8-47 8-47 8-47 A Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 A.1 Integral Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 A.2 CONFIG Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 A.3 CURSOR Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5 A.4 ENVIRONMENT Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7 A.5 FONTINFO Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8 A.6 MODEINFO Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 A.7 OFFSCREEN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13 A.8 PALET Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14 A.9 PATTERN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15 TIGA Reserved Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.1 Reserved Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.2 TIGA Core Functions Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.3 TIGA Extended Graphics Library Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 B-2 B-3 B-6 B C Debugger Support for TIGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1 C.1 Debugger Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2 Table of Contents xii Contents C.2 C.3 D TIGA / Debugger Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-12 Compatibility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-14 D-1 D-2 D-3 D-7 Error Messages / Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.1 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.2 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.3 Communication Driver (CD) Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1 xiii Figures 1-1. 1-2. 4-1. 6-1. 6-2. 6-3. 6-4. 6-5. 6-6. 6-7. 6-8. 7-1. 7-2. 7-3. 8-1. 8-2. 8-3. 8-4. Block Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Function Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Outcodes for Lines Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Screen Coordinates and Drawing Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Mapping of Pixels to Coordinate Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 A Filled Rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 A Filled Polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 An Outlined Polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 A Line Drawn by a Pen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 A 16-by-16 Area-Fill Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 Three Connected Styled Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14 Bit-Mapped Font Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Data Structure for Bit-Mapped Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 Bit-Mapped Font Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9 Command Number Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 Data Structure of dm_cmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18 Data Structure of dm_psnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20 Data Structure of dm_poly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23 xiv Table of Contents Tables 3-1. 3-2. 3-3. 3-4. 3-5. 3-6. 3-7. 3-8. 3-9. 3-10. 3-11. 3-12. 3-13. 3-14. 3-15. 3-16. 3-17. 3-18. 4-1. 4-2. 6-1. 6-2. 6-3. 6-4. 6-5. 7-1. 7-2. 7-3. 8-1. 8-2. 8-3. 8-4. Include Files for PC Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 AI Libraries Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Include Files for TIGA Extended Function Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Graphics System Initialization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 Clear Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Graphics Attribute Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Palette Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 Graphics Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 Poly Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 Pixel Array Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 Text Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 Graphics Cursor Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 Graphics Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16 Handle-Based Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17 Pointer-Based Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17 Data Input /Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 Extensibility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 Interrupt Handler Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 Pixel-Processing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43 Pixel-Processing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-120 Geometric Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Rendering Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Checklist of Available Geometric Types and Rendering Styles . . . . . . . . . . . . . . . . . . . . . . 6-3 Boolean Pixel-Processing Operation Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17 Arithmetic Pixel-Processing Operation Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17 Text-Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Font Database Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 Installable Font Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15 Keyword Equivalent Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13 Trap Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-36 Interrupt Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-37 Linking Loader Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-45 xv Examples 8-1. 8-2. 8-3. 8-4. 8-5. 8-6. 8-7. 8-8. 8-9. Installation of the RLM example.rlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6 Creation of an ALM From EXAMPLE.RLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 TMS340 Shell Routine With dm_poly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24 C Code to Determine the TMS340 Processor Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-39 Assembly Code to Determine the TMS340 Processor Type . . . . . . . . . . . . . . . . . . . . . . . . 8-40 Initialization of the CONVSP Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-41 Initialization of the Video Timing I/O Register Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-42 Use of TMS34020-Specific Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-43 Use of the VFILL Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-44 xvi Table of Contents Chapter 1 Introduction This user's guide describes TIGA (Texas Instruments Graphics Architecture), a software interface that standardizes communication between application software and all TMS340 family-based hardware for IBM-compatible personal computers. TIGA divides tasks between the TMS340 processor and the 80x86 host to improve application performance. The TIGA interface standard simplifies the development of portable applications and application drivers for the diverse range of TMS340-based systems. TIGA's function set can be easily extended and customized by software developers for an application's specific needs. In addition, hardware developers can customize TIGA to take advantage of any value-added features available on the target TMS340-based board. 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. Topics in this chapter include Section Page 1.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 1.3 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 1-1 Features 1.1 Features These are the key application-related features of the TIGA interface standard: Applications run faster TIGA provides the application developer with a dual-processor environment. This environment partitions the tasks in the application to run in parallel between the host and the TMS340 processors. The TIGA 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. TIGA supports the complete line of TMS340x0 graphics system processors from Texas Instruments. TIGA's functions take advantage of any available enhanced TMS340 processor instructions. TIGA supports both real- and protected-mode DOS applications. TIGA provides applications with a base set of graphics functions and with all the support required for the graphics subsystem. TIGA is compatible with a variety of popular DOS and extended DOS development tools. When an application requires graphics functions that are not available in the TIGA base set of functions, you can develop userextended functions by using TMS340 C, assembly language, or a mixture of the two. These extended graphics library functions can be downloaded at runtime during the application initialization. Inquiry functions enable the application to determine the resolution, pixel size, etc., of the graphics subsystem and to adapt itself to the TMS340-based board on which it runs. TMS340 family support Dual-mode support Easy to use Extensible Hardware independent 1-2 Introduction Architecture 1.2 Architecture Figure 1-1 shows a block diagram of the TIGA 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) a) Communication Driver (CD) b) Graphics Manager (GM) c) TIGA Extensions Figure 1-1. Block Diagram GRAPHICS MANAGER Application APPLICATION INTERFACE Command Executive TIGA Interface COMMUNICATION DRIVER (TSR) TIGA Functions User-Extended Functions Host PC TMS340 Board The application interface (AI) provides the communication path between a TIGA application and the TIGA communication driver. 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 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. The application invokes these functions via calls in the AI. These communication functions control the host side hardware-dependent 1-3 Architecture portion of TIGA, including whether the TMS340 board is memory-mapped or I/O-mapped. The graphics manager (GM) is the portion of TIGA that runs on the TMS340 board and is specific to the board that it resides on. It consists of a command executive that controls the TMS340 side of the communications with the host, and of a set of core functions that provide memory management, palette support, and low-level graphics support. The GM typically resides in RAM on the TMS340 board (although this is not a requirement) and therefore must be loaded onto the board after power-up. The task of loading the GM is handled automatically by TIGA. In addition to its core functions,TIGA also provides a set of functions to perform a wide range of graphics drawing operations. TIGA's functions can be extended by downloading additional, user-developed functions onto the TMS340 system. These downloaded functions may be written with either the TMS340 C or assembly language. Downloading functions can decrease the amount of processing required by the host 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 identifier for the 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-4 Introduction Extensibility 1.3 Extensibility Graphics standards that existed prior to TIGA limited software development by providing a fixed set of graphics drawing functions. In the rapidly changing graphics market, a fixed set of functions is unacceptable. TIGA's functions can be extended by adding or manipulating its user library collection of C-callable routines. Figure 1-2 shows the configuration options for TIGA functions. Figure 1-2. Function Configuration Options Base Set of TIGA Functions Hardware and Software Developer Options or TIGA Graphics Library (example: patnfill_oval) TIGA Extended Functions Core Functions (example: gsp_malloc) Core Functions TIGA-compatible applications can be developed by using the base set of functions provided by TIGA (as shown in the left-hand side of Figure 1-2). These TIGA functions include the core functions, which are always available to the application, and the TIGA graphics library functions, which can be loaded if the application requires them.This set of graphics functions and the TMS340 processor give many applications an acceptable level of graphics performance. However, downloading user-extended functions can improve this performance still further. The user-extended functions can be downloaded to be used in addition to or instead of the TIGA graphics library (as shown on the righthand side of Figure 1-2). The same concept of adding functions can be implemented in hardware. For example, if you develop a TMS340-based graphics system and incorporate hardware in addition to the TMS340 processor, you can provide access to this EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE User-Extended Functions Core Functions EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE EEEEEEEE User-Extended Functions 1-5 Extensibility hardware through the TIGA interface by developing a set of user-extended functions that use the additional hardware functionality. Thus, the TIGA interface becomes a standard programming platform for the software written with these user-extended functions. 1-6 Introduction Chapter 2 Getting Started This chapter contains instructions for installing TIGA on your system. Topics in this chapter include Section Page 2.1 TIGA Development Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 2.2 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.3 Installing TIGA on Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.4 Modifying Autoexec and the Environment . . . . . . . . . . . . . . . . . . . . . 2-7 2.5 The TIGA Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 2.6 Running the TIGA Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 2.7 TIGA Utility Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 2.8 Rebuilding Existing TIGA Applications for TIGA 2.0 . . . . . . . . . . . . 2-13 2-1 TMS340 Development Products 2.1 TMS340 Development Products Three TMS340 software development products are available from Texas Instruments: DDK: TMS340 Driver Developer's Kit (TI part number TMS340DDK-PC) The DDK is intended for software developers writing TIGA-compatible applications and drivers, for which no TIGA extension development is required. The TIGA Driver Development Package (TIGA-DDP), a subassembly of the DDK, contains the TIGA-related files and information. SDK: TMS340 Software Developer's Kit (TI part number TMS340SDKPC) The SDK is intended for software developers writing TIGA-compatible applications and drivers, for which TIGA extension development is required. The TIGA Software Development Package (TIGA-SDP), a subassembly of the SDK, contains the TIGA-related files and information. Other subassemblies included with the SDK are the TMS340 Code Generation Tools and the TMS340 Graphics Library. SPK: TMS340 Software Porting Kit (TI part number TMS340SPK-PC) The SPK is intended for OEMs porting TIGA to their TMS340-based video hardware. The TIGA Software Porting Package (TIGA-SPP), a subassembly of the SPK, contains the TIGA-related files and information. Other subassemblies included with the SPK are the TMS340 Code Generation Tools and the TMS340 Graphics Library. 2-2 Getting Started System Requirements 2.2 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 package you are installing. 2.2.1 TIGA Driver Development Package (TIGA-DDP) and TIGA Software Development Package (TIGA-SDP) IBM PC, XT, AT, or 100% compatible (hard disk required) 640K RAM TMS340-based TIGA 2.0-compliant video board with TIGA 2.0 driver MS-DOS or PC-DOS, version 2.13 or higher Microsoft Macro Assembler, version 5.0 or higher (if developing assembler-based applications/drivers) Microsoft C Compiler, version 5.0 or higher (if developing DOS real-mode C applications) MetaWare High C compiler, version 1.5 or 1.7, or Microway NDP C compiler, version 2.0 or higher, and Phar Lap 386 development tools, version 2.2 (if developing DOS protected-mode applications/drivers). TMS340 Family Code Generation Tools, version 4.0 or higher (if writing user-extended functions) 2.2.2 TIGA Software Porting Package (TIGA-SPP) IBM PC, XT, AT, or 100% compatible (hard disk required) 640K RAM TMS340-based video board (TIGA 2.0 target platform) MS-DOS or PC-DOS, version 2.13 or higher Microsoft Macro Assembler, version 5.0 or higher Microsoft C Compiler, version 5.0 or higher TMS340 Family Code Generation Tools, version 4.0 or higher Note: The TIGA-SPP provides complete porting sources to build and run TIGA 2.0 on a Texas Instruments TMS34010 or TMS34020 software development board, or on the TMS34010-based TIGA Development Board (TDB). In addition, all software necessary to port TIGA to a different TMS340 board is included in the TIGA-SPP; consult the Porting Guide in the file \tiga\docs\portguid.doc for information. 2-3 Installing TIGA on Your System 2.3 Installing TIGA on 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 directory. For this reason, you should back up files of previous versions of TIGA, if needed, before proceeding with the new TIGA installation. All TIGA development packages have an automated installation program with identical procedures to aid in installing TIGA on your system. Follow these instructions to install your TIGA kit: Step 1: Make backup copies of the product diskettes. Step 2: Place diskette #1 (DDP #1, SDP #1, or SPP #1) of your TIGA kit into drive A. Step 3: If A is not your current drive, at the MS-DOS prompt enter A: Step 4: Make sure you are at the root directory of A. If you are not sure, enter this at the MS-DOS prompt: cd\ Step 5: Enter setup Step 6: Follow the instructions displayed on the screen to complete installation. Note: After installing TIGA, consult the \tiga\docs\readme.1st file for the latest information not included in this user's guide. The installation of your TIGA development package creates a number of subdirectories on your destination drive. Consult one of the following three sections (depending on the TIGA development package you installed) for information describing these subdirectories and the files contained within them. 2-4 Getting Started Installing TIGA on Your System 2.3.1 TIGA Driver Development Package (TIGA-DDP) Subdirectories Installing the TIGA-DDP on your system creates the following subdirectories: Subdirectory Description \tiga TIGA root directory, TIGA drivers, system files, and utility programs \tiga\demos TIGA-compatible example programs \tiga\docs Additional TIGA-related documentation \tiga\fonts TIGA-compatible fonts \tiga\include Include files \tiga\libs Application interface libraries 2.3.2 TIGA Software Development Package (TIGA-SDP) Subdirectories Installing the TIGA-SDP on your system creates the following subdirectories: Subdirectory Description \tiga TIGA root directory, TIGA drivers, system files, and utility programs \tiga\demos TIGA-compatible example programs \tiga\docs Additional TIGA-related documentation \tiga\fonts TIGA-compatible font files \tiga\gm\extprims TIGA-extended graphics library files \tiga\include Include files \tiga\libs Application interface libraries The \tiga\gm\extprims directory contains the self-extracting archive file extprims.exe. This archive contains source for every extended graphics library 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 extract the source files contained in this archive, enfrom within this directory. ter extprims 2.3.3 TIGA Software Porting Package (TIGA-SPP) Subdirectories Installing the TIGA-SPP on your system creates the following subdirectories: Subdirectory Description \tiga TIGA root directory, TIGA drivers, system files, and utility programs \tiga\cd Common TIGA communication driver (CD) files \tiga\cd\cd34010 TMS34010 common CD files \tiga\cd\cd34020 TMS34020 common CD files \tiga\cd\tdb10 TIGA Development Board-specific CD files \tiga\cd\sdb10 TMS34010 SDB-specific CD files 2-5 Installing TIGA on Your System Subdirectory \tiga\cd\sdb20 \tiga\demos \tiga\docs \tiga\fonts \tiga\gm \tiga\gm\corprims \tiga\gm\extprims \tiga\gm\tdb10 \tiga\gm\sdb10 \tiga\gm\sdb20 \tiga\include \tiga\libs Description TMS34020 SDB-specific CD files TIGA-compatible example programs/drivers Additional TIGA-related documentation TIGA-compatible font files TIGA Graphics Manager (GM) files TIGA core function files TIGA-extended graphics library files TIGA Development Board-specific GM files TMS34010 SDB-specific GM files TMS34020 SDB-specific GM files Include files Application interface (AI) libraries Refer to the file portguid.doc in the \tiga\docs directory for detailed instructions on how to port TIGA to your TMS340-based video board. 2-6 Getting Started Modifying Autoexec and the Environment 2.4 Modifying Autoexec and the Environment After installing your TIGA package, you will need to 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 designator for the drive where you installed your particular TIGA package: 1) Append C:\tiga to the MS-DOS path: PATH=existing PATH;C:\tiga 2) If you plan to develop TIGA-compatible applications using the Microsoft C Compiler, append C:\tiga\include to the Microsoft C compiler environment variable INCLUDE: set INCLUDE=existing 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 Family Code Generation Tools installed on your system, then append C:\tiga\include to the existing A_DIR and C_DIR environment variables: set A_DIR=existing A_DIR;C:\tiga\include set C_DIR=existing 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 -lC:\tiga -i0x60 See Section 2.5 for a complete description of the TIGA environment variable. 5) After modifying your autoexec.bat file, run it or reboot your PC. 2-7 The TIGA 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 by using the following syntax: set TIGA = [options] [string] [options] [string] set TIGA is the command that sets the environment options valid options include -m specifies the path for TIGA system files -l specifies the path for TIGA dynamic load user modules -i specifies the host interrupt level used by the TIGA communication driver The option string cannot contain the character '-'. In addition, there should be no spaces between the option and the option string. For example: set TIGA=-mc:\tiga is correct set TIGA=-m c:\tiga is incorrect Also, a space is required between options. For example: set TIGA=-mc:\tiga -lc:\tiga is correct set TIGA=-mc:\tiga-lc:\tiga is incorrect When TIGA is initially installed, all TIGA system files are placed in the TIGA directory of the destination drive. Specify this path with the -m option of the TIGA environment variable. Any dynamic load modules loaded from a TIGA application must be located in either the current directory from which the TIGA application is called, or the path specified by the -l option in the TIGA environment variable. By default, TIGA's communication driver uses interrupt level 0x7F to communicate with an application. Use the -i option followed by the interrupt level (in hex format) in the TIGA environment variable to specify an alternate interrupt level. Note: The TIGA interrupt level must be set below 0x70 for the TIGA CD to operate properly with the Phar Lap utilities (that is, applications linked with the MetaWare High C or NDP C compilers). TI recommends using 0x60. For example, assume that all TIGA system files are located in C:\tiga, that user dynamic load modules are in D:\dlm, and that the desired interrupt level to use is 0x60. Set the corresponding TIGA environment variable: set TIGA= -mc:\tiga -ld:\dlm -i0x60 2-8 Getting Started Running the TIGA Driver 2.6 Running the TIGA Driver This section provides general instructions on how to load the TIGA communication driver. Consult the TIGA software installation instructions that accompany your TIGA video board for specific loading information. To load TIGA, enter this at the MS-DOS prompt: tigacd [options] tigacd options is the command that invokes the TIGA communication driver (CD). valid options include -i Reinstalls the TSR. This option forces a new copy of the TIGA communication driver 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. 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. -u The following options control TIGA's debugger facilities. For detailed information on how to debug a TIGA application, refer to the TMS340 Family C Source Debugger user's guide. -d0 -d1 Disables the TIGA debug facility. Enables the emulator mode of TIGA's debug facility. This option, used in conjunction with the emulator version of the TMS340 C source debugger and the XDS500 emulator, provides C source level debug capability for TIGA applications. Enables the development board mode of the TIGA debug facility. This option, used in conjunction with the serial link configuration of the TMS340 C source debugger, provides C-source-level debug capability for TIGA applications. -d2 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 by an application calling set_videomode(TIGA,INIT) to check 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 before returning from the set_videomode function. After you load the host and TMS340 sides of TIGA, your application is free to call TIGA's core functions. 2-9 TIGA Utility Programs 2.7 TIGA Utility Programs The following TIGA utility programs are in TIGA's root directory \tiga to simplify porting and/or applications development: TIGA Utility cltiga.bat hcc.bat hcl.bat Description Batch file that uses Microsoft C tools to compile and link a TIGA application. Batch file that invokes the MetaWare High C Compiler, compiling the specified source file. Batch file that invokes the Phar Lap linker, linking the object code and optional user library with the MetaWare High C version of the TIGA AI library (hcai.lib). Texas Instruments program maintenance utility. It is fully compatible with the Microsoft make.exe utility and has additional features. Consult the file \tiga\docs\make.doc for detailed usage information. This utility restores the TIGA environment back to a known, stable state. There is always the potential of a TIGA 1.1 application prematurely aborting and not properly restoring the TIGA environment. Run oldap.exe anytime you encounter timeout errors while running TIGA applications under TIGA 2.0. Utility to convert TMS340 math/graphics fonts to TIGAcompatible fonts. Utility to query available modes and select default mode. make.exe oldap.exe mg2tiga.exe tigamode.exe 2.7.1 cltiga Batch File The cltiga.bat batch file easily compiles and links a TIGA-compatible application (contained in a single C source file) to the TIGA application interface library ai.lib, using the Microsoft C compiler. It also supports symbolic debugging through Microsoft's CodeView debugger. The syntax for cltiga is cltiga [-d] filename where: cltiga is a batch file to compile and link a TIGA application, -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 ai.lib is independent of the Microsoft C model. However, the cltiga batch file uses the large model by default. You can override the default by modifying the cltiga.bat file(consult the Microsoft C reference manual for details). 2-10 Getting Started TIGA Utility Programs 2.7.2 mg2tiga Utility The mg2tiga utility converts fonts compatible with the TMS340 Graphics Library to a format compatible with the TIGA text functions. To invoke the mg2tiga utility, enter mg2tiga MG font TIGA font [ "facename" ] mg2tiga is the command to invoke the mg2tiga.exe utility. MG font is a binary or COFF object image of a math/graphics compatible font. TIGA font is the filename under which the converted font is saved. facename is an optional name of the font (up to 29 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 math/ graphics font library to TIGA format. 1) Locate the library that contains TI Roman fonts. As supplied, this library is called ti_roman.lib and contains 12 fonts. To display a table of contents of this library, enter gspar -t ti_roman GSP Archiver Version 4.00 (c) Copyright 1985, 1990, Texas Instruments Incorporated FILE NAME --------ti_rom11.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 Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Thu Jun 12 Wed Jun 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 3) Now use mg2tiga to convert it to TIGA format. Example: mg2tiga ti_rom18.obj roman18.fnt At this point, mg2tiga prompts you to enter a facename for the font. This facename can be up to 29 characters long and should be the name of the font. 2-11 TIGA Utility Programs Example: MGFL to TIGA font converter Enter facename (29 chars max): TI ROMAN After you have entered the facename, mg2tiga displays the MG font header follows each of and then the new TIGA font header. A prompt to press these displays. After you enter this information, the conversion is complete. [ -------- Old Font Header -------- ] fonttype: 9000 firstchar: 0000 lastchar: 00ff widemax: 0010 kernmax: 0000 ndescent: fffd charhigh: 0011 owtloc: 046a ascent: 000e descent: 0003 leading: 0002 rowwords: 0033 [ Press return ]-> [ -------- New Font Header -------- ] magic: 8040 length: 00000b18 facename: TI ROMAN first: 0000 last: 00ff deflt: 0000 maxwide: 0010 maxkern: 0000 charwide: 0000 avgwide: 0008 charhigh: 0011 ascent: 000e descent: 0003 leading: 0002 rowpitch: 00000330 oPatnTbl: 00000250 oLocTbl: 00003880 oOwTbl: 000048a0 [ Press return ]-> 2-12 Getting Started Rebuilding Existing TIGA Applications for TIGA 2.0 2.8 Rebuilding Existing TIGA Applications for TIGA 2.0 Any TIGA application or driver linked with the TIGA 1.1 Application Interface (AI) library will run unchanged under TIGA 2.0. However, if you relink your existing TIGA 1.1 compatible application or driver with one of the TIGA 2.0 AI libraries, several modifications to your source code will be required. This section outlines the modifications required to upgrade existing TIGA 1.1 applications to link with TIGA 2.0 libraries. 2.8.1 TIGA 2.0 Initialization / Termination A new method of initializing and terminating a TIGA application has been added to TIGA 2.0. This was required to support TIGA's ability to run both real- and protected-mode DOS applications. TIGA 1.1 initialization was accomplished by calling one of the following two functions: cd_is_alive() set_videomode(TIGA, style) Both establish communications with the TIGA communication driver. In addition, the set_videomode function loads the TIGA graphics manager if specified to do so by the style argument. A new function, tiga_set, has been added to TIGA 2.0 for properly initializing and terminating the TIGA environment from an application. This function replaces the cd_is_alive function formerly used in TIGA 1.1. In addition, the TIGA 2.0 version of the set_videomode function only switches video modes and does not initialize communications. TIGA 2.0 applications must call tiga_set(CD_OPEN) before calling any other TIGA function and must call tiga_set(CD_CLOSE) before returning to DOS. This will insure that the TIGA environment is properly maintained. Refer to the sample TIGA 2.0 application listing in Section 3.4, page 3-6, and to the tiga_set function description in Chapter 4, page 4-136, for more information. 2.8.2 CURSOR Structure Change TIGA's CURSOR structure has been modified to support two-color cursors. TIGA 1.1 allowed only the cursor shape color to be modified. TIGA 2.0 now allows both the cursor mask and shape colors to be specified. Any existing source code using the TIGA CURSOR structure must be modified to conform to the TIGA 2.0 CURSOR structure definition. 2-13 Rebuilding Existing TIGA Applications for TIGA 2.0 The TIGA 1.1 CURSOR structure was defined as typedef struct { short hot_x; short hot_y; unsigned short width; unsigned short height; unsigned short pitch; unsigned long color; unsigned short mask_rop; unsigned short shape_rop; PTR data; }CURSOR; /* /* /* /* /* /* /* /* /* hotspot offset from top left-hand corner cursor width (in bits) cursor height (lines) pitch of cursor data cursor shape color cursor mask rop cursor shape rop pointer to cursor data in TMS340 memory */ */ */ */ */ */ */ */ */ The TIGA 2.0 CURSOR structure has an additional field, mask_color, along with transparency support added to the rop fields: typedef struct { short hot_x; short hot_y; unsigned short width; unsigned short height; unsigned short pitch; unsigned long color; unsigned short mask_rop; unsigned short shape_rop; unsigned long mask_color; PTR data; }CURSOR; /* /* /* /* /* /* /* /* /* /* hotspot offset from top left-hand corner cursor width (in bits) cursor height (lines) pitch of cursor data cursor shape color cursor mask rop cursor shape rop cursor mask color pointer to cursor data in TMS340 memory */ */ */ */ */ */ */ */ */ */ Consult the set_curs_shape and set_cursattr function descriptions in Chapter 4 for additional information. 2.8.3 Return Value of set_config The TIGA 2.0 Graphics Manager (GM) is relocatable to support varying memory maps. Specifying a particular graphics mode with the set_config function may cause the TMS340 memory map to change, which in turn could force the GM to be reloaded. This may have undesirable results, since reloading the GM causes all downloaded extensions to be flushed and all allocated memory to be freed. The return value of the TIGA 2.0 set_config function can be used by an application to query whether the GM was reloaded. If so, the application can take the appropriate steps necessary to return the TMS340 environment back to a known state. However, it is recommended that any application that calls set_config does so before downloading any TIGA extensions or allocating any memory. See the set_config function description, page 4-100, for more information. 2-14 Getting Started Rebuilding Existing TIGA Applications for TIGA 2.0 2.8.4 Elimination of Offscreen Workspace The TIGA 1.1 fill_polygon and patnfill_polygon functions both required the use of a one-bit-per-pixel offscreen workspace to operate properly. In TIGA 2.0, these functions have been modified to remove this restriction. You may wish to remove existing code used to initialize the offscreen workspace area; it is no longer required by any function in TIGA 2.0. 2.8.5 TIGA 1.1 Functions No Longer Supported Only one function previously available in TIGA 1.1 is no longer supported in TIGA 2.0. It is the cd_is_alive function. Consult subsection 2.8.1 for additional information. 2.8.6 New Functions Available in TIGA 2.0 TIGA 2.0 provides a variety of new functions, which are listed in this section. Also, many existing TIGA 1.1 functions have been modified to provide additional functionality. For further information, consult the appropriate function's description in Chapter 4, for core functions, and in Chapter 5, for extended graphics library functions. New TIGA 2.0 core functions: aux_command cvxyl flush_module get_text_xy gm_idlefunction gsph_alloc gsph_calloc gsph_compact gsph_deref gsph_falloc gsph_fcalloc gsph_findhandle gsph_findmem gsph_free gsph_init gsph_maxheap gsph_memtype gsph_realloc gsph_totalfree setup_hostcmd set_cursattr set_module_state set_text_xy sym_flush text_outp tiga_busy tiga_set New TIGA 2.0 extended graphics library functions: decode_rect put_pixel encode_rect styled_oval get_pixel styled_ovalarc in_font styled_piearc move_pixel 2.8.7 Functional Differences in TIGA 2.0 get_pmask The TIGA 2.0 implementation returns the value of the plane mask register right-justified (and zero-extended) in 2-15 Rebuilding Existing TIGA Applications for TIGA 2.0 gsp_minit page_flip set_pmask graphics cursors the N LSBs of the return value, where N is the current pixel size. The TIGA 1.1 implementation of get_pmask simply returned the current 32-bit value in the plane mask register. The stack size argument supplied to the gsp_minit function is ignored in TIGA 2.0 because of limitations imposed by the new TIGA 2.0 memory manager. Note however, that an argument must still be specified for the function. The TIGA 1.1 implementation of page_flip returned zero if an invalid drawing or display page argument was specified, and nonzero if the specified arguments were valid. The TIGA 2.0 implementation of page_flip does not return a value and treats invalid display and/or drawing page arguments as if the function were called as page_flip(0,0). The TIGA 2.0 implementation of set_pmask automatically replicates the right-justified N LSBs (where N is the current pixel size) of the mask argument, throughout the 32-bit plane mask register. The TIGA 1.1 implementation expected the mask argument to be already replicated. The TIGA 2.0 cursor generator automatically saves and restores the current PMASK register, then clears it to zero (enables all bit planes) before saving the cursor background, drawing the cursor, and restoring the original background. Earlier versions of the cursor generator simply used whatever value was currently set in PMASK. 2-16 Getting Started Chapter 3 Application Interface TIGA consists of a set of functions that a host-PC application can invoke to perform a variety of graphics-related tasks (a host-PC application is defined as that portion of the application that is running on the host-PC processor). These functions may run entirely on the host-PC or the TMS340 board, or they may execute in parallel on both processors. TIGA also gives the application developer the capability to create functions that are downloaded to the TMS340-based target board by the host-PC application. Because these functions are not part of the standard TIGA core functions, and because they reside and run on a TMS340-based board, they are commonly referred to as extended functions. Once these extended functions are loaded, the host-PC application may call them at any time. In addition, an extended function may call a core function, a previously loaded extended function, or even a function residing on the host-PC side of the application. Detailed information on how to create, load, and call TMS340 extended functions is presented in Chapter 8. This chapter discusses basic information required to develop a TIGA-compatible application. It also lists the TIGA functions in their functional groups. Topics in this chapter include Section Page 3.1 Supported Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3.2 Host-PC Include Files and Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 3.3 TMS340 Include Files and Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 3.4 Sample TIGA Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 3.5 TIGA Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 3.6 Summary of Functions by Functional Group . . . . . . . . . . . . . . . . . . 3-12 3-1 Supported Development Tools 3.1 Supported Development Tools The following development tools are currently supported by TIGA 2.0. Note: Consult the \tiga\docs\readme.1st file for information describing any additional development tools supported by TIGA 2.0. 3.1.1 Host-PC Development Tools Version 5.0 or higher 5.0 or higher 1.5 or 1.7 2.0 or higher Operating System DOS (real mode) DOS (real mode) Phar Lap DOS Extender v 2.2 Phar Lap DOS Extender v 2.2 Compiler/Assembler Microsoft C Compiler Microsoft Macro Assembler MetaWare High-C Compiler Microway NDP C-386 Compiler Note: The examples in this user's guide are intended to be built with the Microsoft C Compiler. Minor modifications may be required to build the examples with any of the other supported development tools listed above. 3.1.2 TMS340 Development Tools The TMS340 Family Code Generation Tools, version 3.0 or higher, are used to build TMS340 extended functions. You will need these tools only if you are planning on writing your own extended functions. 3-2 Application Interface Host PC Include Files and Libraries 3.2 host-PC Include Files and Libraries Three types of TIGA includes files are used for developing host-PC TIGA-compatible applications: tiga.* Contains TIGA constants commonly required by a TIGA application and core function references. Every TIGA host-PC application must include and specify this file before any other TIGA include file. Contains references used for the TIGA 2-D Graphics Library. Any application calling a function from this TMS340 extended library must include this file. Contains references for TIGA structures. Any application using a TIGA structure type must include this file. extend.* typedefs.* These include files are located in the \tiga\include directory. Different versions of each include file type are provided for each set of supported development tools. Table 3-1 summarizes the include files provided in TIGA 2.0 for host-PC code development: Table 3-1.Include Files for PC Development Microway NDP C-386 tiga.* extend.* typedefs.* tiga.ndp extend.pl typedefs.pl MetaWare High C 386 tiga.hch extend.pl typedefs.pl Microsoft C (all models) tiga.h extend.h typedefs.h Microsoft Assembler tiga.inc, tiga_sm.inc extend.inc typedefs.inc After you compile and/or assemble the host-PC source program, you must link the derivative object file(s) with the appropriate TIGA Application Interface (AI) library. The functions within this library provide the communications interface between the application and the TIGA Communication Driver (CD). All TIGA AI libraries are located in the \tiga\libs directory. Different versions of the AI library are provided for each set of supported development tools. Table 3-2 summarizes the AI libraries provided in TIGA 2.0 for linking host-PC developed code. In addition,Table 3-2 lists the code/data referencing type, memory models, and compatible development tools for each TIGA AI library. 3-3 Host PC Include Files and Libraries Table 3-2.AI Libraries Development Tools TIGA AI Library ai.lib ai_com.lib hcai.lib ndpai.lib Description Far code references, Far data references Near code references, Near data references Near code references, Near data references Near code references, Near data references Development Tools Microsoft C 5.0 or higher, Microsoft Macro Assembler Microsoft C 5.0 or higher, Microsoft Macro Assembler MetaWare High C Microway NDP C Memory Models small, medium, compact, large, huge .com not applicable not applicable 3-4 Application Interface TMS340 Include Files and Libraries 3.3 TMS340 Include Files and Libraries A standard set of include files supports development of extended functions for TIGA. TIGA extensions may be developed in C or TMS340 assembly code. See Chapter 8 for more information on how to develop TMS340 extensions to TIGA. The TIGA TMS340 include files and libraries are identified by the leading characters gsp (Graphics System Processor). In addition to the three types of include files described in Section 3.2, three other include file types are provided for developing TIGA extended functions: gspglobs.* Contains references to TIGA global variables, arrays, and structures. Include this file if your TMS340 extended functions reference any TIGA variable, array, or structure. Contains equated constants for all TMS34010 and TMS34020 processor registers. Contains macros useful for developing TMS340 assembly code. Consult the \tiga\docs\gspmac.doc file for a description of the macros in this library. gspreg.* gspmac.lib Table 3-3 summarizes the include files and libraries provided in TIGA 2.0 for TMS340 extended function development: Table 3-3.Include Files for TIGA Extended Function Development TMS340 C gsptiga.* gspextnd.* gsptypes.* gspglobs.* gspreg.* gspmac.lib gsptiga.h gspextnd.h gsptypes.h gspglobs.h gspreg.h - TMS340 Assembler gsptiga.inc gspextnd.inc gsptypes.inc gspglobs.inc gspreg.inc gspmac.lib 3-5 Sample TIGA Application 3.4 Sample TIGA Application This section describes the basic components of a TIGA application. In general, all TIGA applications contain the following: Initialization Load TIGA extended functions (optional) Main body Termination The initialization establishes the communications link between the application and the TIGA communication driver. Also, correct operation of the TIGA graphics manager is verified. Initialization is extremely important to ensure a stable TIGA environment for your application. After initialization is complete, the application may call any of TIGA's core functions. However, this set of functions may be insufficient for your application. Additional required functions are normally loaded into TIGA following initialization. These extended functions may include TIGA's graphics library and/or any other required extended function library. Once all functions are loaded into TIGA, the application can call them at any time throughout the main body of the application. Finally, the TIGA environment must be properly terminated. This step restores the video environment to the state it was in before you executed the TIGA application. The following example TIGA application illustrates how to set up the TIGA environment, load extended functions, and then terminate the TIGA environment. /********************************************************************************/ /* Sample TIGA 2.0 application */ /* */ /* This example illustrates the basic components of a TIGA app: */ /* */ /* - Initialization */ /* - Loading extended functions */ /* - Main body */ /* - Termination */ /* */ /* This example is intended to be built with the Microsoft 'C' */ /* compiler. */ /********************************************************************************/ #include Application Interface Sample TIGA Application /*------------------------------------------------------------------------------*/ /* term_tiga */ /* */ /* syntax void term_tiga(void) */ /* */ /* This function properly terminates a TIGA application by */ /* restoring the previous video mode and closing the TIGA CD. */ /* It must be called prior to returning to DOS. */ /*------------------------------------------------------------------------------*/ void term_tiga() { printf("Press any key to return to DOS..."); getch(); set_videomode(oldmode,INIT); /* Return mode to prev state */ tiga_set(CD_CLOSE); /* Close the TIGA CD */ exit(0); /* Exit back to DOS */ } /*------------------------------------------------------------------------------*/ /* init_tiga */ /* */ /* syntax void init_tiga(load_graphics_lib) */ /* short load_graphics_lib; */ /* */ /* This function properly initializes the TIGA environment */ /* and loads the graphics library functions if argument */ /* load_graphics_lib is non-zero. This function should be */ /* called prior to calling any other TIGA function. */ /*------------------------------------------------------------------------------*/ void init_tiga(load_graphics_lib) short load_graphics_lib; { short v; long lv; /*--------------------------------------------------------------------------- * / /* Open TIGA Communications Driver */ /*--------------------------------------------------------------------------- * / if((lv = tiga_set(CD_OPEN)) < 0L) { printf("TIGA CD error: %ld\n", lv); exit(0); /* Exit back to DOS */ } 3-7 Sample TIGA Application /*--------------------------------------------------------------------------- * / /* Go into TIGA mode */ /*--------------------------------------------------------------------------- * / oldmode = get_videomode(); /* Save current videomode for later */ if(!(v = set_videomode(TIGA,INIT | CLR_SCREEN))) { printf("TIGA GM error: %d\n", v); tiga_set(CD_CLOSE); /* Be sure to close the open TIGA CD */ exit(0); /* before exiting to DOS */ } /*--------------------------------------------------------------------------- * / /* Load graphics library functions if specified to do so */ /*--------------------------------------------------------------------------- * / if(load_graphics_lib && (v=install_primitives()) < 0) { printf( "Graphics Library load error: %d\n", v ); term_tiga(); } } 3-8 Application Interface Sample TIGA Application /*------------------------------------------------------------------------------*/ /* Main program. */ /*------------------------------------------------------------------------------*/ main() { CONFIG config; /* Storage for TIGA config struct */ short width,height,xleft,ytop; /* fill_rect() arguments */ /*--------------------------------------------------------------------------- * / /* Call init_tiga() to initialize the TIGA environment. Also, */ /* load the Graphics Library functions. */ /*--------------------------------------------------------------------------- * / init_tiga(1); /*--------------------------------------------------------------------------- * / /* Load extended functions section (OPTIONAL) */ /* */ /* At this point, the TIGA environment has been properly */ /* initialized. This is a good time to load any other extended */ /* functions required by the application. */ /*--------------------------------------------------------------------------- * / : : /*--------------------------------------------------------------------------- * / /* Main body */ /* */ /* All functions are now loaded. We can now safely call any of */ /* these functions. */ /* */ /* As an example, let's draw a blue, solid filled rectangle, */ /* half the size of the screen, centered in the screen. */ /*--------------------------------------------------------------------------- * / get_config(&config); width = config.mode.disp_hres >> 1; height = config.mode.disp_vres >> 1; xleft = width >> 1; ytop = height >> 1; set_fcolor(BLUE); fill_rect(width,height,xleft,ytop); : : : term_tiga(); } /* /* /* /* /* /* /* Get info on current mode Width 1/2 screen width Height 1/2 screen height Center rect in middle of screen Set foreground color Fill the rectangle */ */ */ */ */ */ */ /* Properly terminate TIGA */ All example programs provided with the function descriptions in this user's guide use similar methods to properly initialize and terminate the TIGA environment. You will notice that, to simplify the source code listings, each example makes calls to the functions init_tiga and term_tiga. The above source code listings of init_tiga and term_tiga are an example of how to properly initialize and terminate the TIGA environment from a TIGA 3-9 Sample TIGA Application application. Your initialization and termination code may differ slightly from the one presented here but should provide similar functionality. 3-10 Application Interface TIGA Functions 3.5 TIGA Functions A TIGA function falls into one of two classes: Core functions Extended functions 3.5.1 Core Functions TIGA's core functions are always available to an application following proper initialization of the TIGA environment as shown in the example in Section 3.4. The majority of core functions can be called by host-PC applications and any extended function. There are, however, a few core functions that can be called only by a host-PC application and may not be called by an extended function. These functions are referred to as host-only core functions and are identified as such in Chapter 4. 3.5.2 Extended Functions Extended functions are not a part of TIGA's core function set and must be explicitly loaded by an application before the application can call them. TIGA includes an extended graphics library that contains a comprehensive set of 2-D drawing functions. The functions in this library are examples of extended functions because they must be loaded into TIGA via the install_primitives() function before being available to the application. 3-11 Summary of Functions by Functional Group 3.6 3.6.1 Summary of Functions by Functional Group Graphics System Initialization Functions The graphics system initialization functions perform the initializing, terminating, and inquiring of the TIGA environment. Before a TIGA function is called, the TIGA environment must be properly initialized. Similarly, once the TIGA application has completed, the graphics environment, which existed prior to running the TIGA application, must be properly restored. These initialization and termination tasks are handled by the functions shown in Table 3-4. Table 3-4.Graphics System Initialization Functions Function aux_command function_implemented get_config get_modeinfo get_videomode gm_idlefunction gsp_execute install_primitives install_usererror loadcoff set_config set_timeout set_videomode setup_hostcmd synchronize tiga_busy tiga_set Description Execute auxiliary command Return if function is implemented Return hardware configuration information Return graphics mode information Return current video mode Enable/disable GM idle function Execute a COFF program Install extended graphics library functions Install user error handler Load COFF file Set hardware configuration Set timeout delay value Set video mode Initialize callback environment Synchronize host and TMS340 communications Determine if TIGA is busy Open/close/query communication driver Type Host Host Core Host Host Core Host Host Host Host Host Host Host Host Host Host Host 3.6.2 Clear Functions The clear functions, shown in Table 3-5, provide different ways to clear the screen. They all attempt to use any special memory functions (such as shift-register transfers), that the board or the memory chips themselves may have, to perform as quickly as possible. 3-12 Application Interface Summary of Functions by Functional Group Table 3-5.Clear Functions Function clear_frame_buffer clear_page clear_screen Description Clear frame buffer Clear current drawing page Clear screen Type Core Core Core 3.6.3 Graphics Attribute Control Functions The graphics attribute control functions, shown in Table 3-6, are used to modify and query graphics attributes used by the TIGA drawing functions when drawing to the screen. See Chapter 6, Graphics Library Conventions, for additional information concerning graphics attributes. Table 3-6.Graphics Attribute Control Functions Function cpw get_colors get_env get_pmask get_ppop get_transp get_windowing set_bcolor set_clip_rect set_colors set_draw_origin set_fcolor set_patn set_pensize set_pmask set_ppop set_transp set_windowing transp_off transp_on Description Compare point to clipping window Return foreground and background colors Return graphics environment information Return plane mask Return pixel-processing operation code Return transparency flag Return window-clipping mode Set background color Set clipping rectangle Set foreground and background colors Set drawing origin Set foreground color Set current pattern address Set pen size Set plane mask Set pixel-processing operation code Set transparency mode Set window-clipping mode Turn transparency off Turn transparency on Type Core Core Ext Core Core Core Core Core Core Core Ext Core Ext Ext Core Core Core Core Core Core 3-13 Summary of Functions by Functional Group 3.6.4 Palette Functions The palette functions, shown in Table 3-7, provide a board-independent way to modify and query palette values on the target TMS340-based board. See the example TIGA program in the directory \tiga\demos\msc\tigademo for more information on color and palette management with TIGA. Table 3-7.Palette Functions Function get_nearest_color get_palet get_palet_entry init_palet set_palet set_palet_entry Description Return nearest color in palette Read entire palette Return single palette entry Initialize palette Set multiple palette entries Set single palette entry Type Core Core Core Core Core Core 3.6.5 Graphics Drawing Functions The graphics drawing functions, shown in Table 3-8, are self-explanatory. For further details concerning the drawing functions, see Chapter 6. Table 3-8.Graphics Drawing Functions Function draw_line draw_oval draw_ovalarc draw_piearc draw_point draw_polyline draw_rect fill_convex fill_oval fill_piearc fill_polygon fill_rect Description Draw straight line Draw ellipse outline Draw ellipse arc Draw ellipse pie arc 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 Type Ext Ext Ext Ext Ext Ext Ext Ext Ext Ext Ext Ext 3-14 Application Interface Summary of Functions by Functional Group Table 3-8. Graphics Drawing Functions (Continued) Function frame_oval frame_rect patnfill_convex patnfill_oval patnfill_piearc patnfill_polygon patnfill_rect patnframe_oval patnframe_rect patnpen_line patnpen_ovalarc patnpen_piearc patnpen_point patnpen_polyline pen_line pen_ovalarc pen_piearc pen_point pen_polyline put_pixel seed_fill seed_patnfill styled_line styled_oval styled_ovalarc styled_piearc Description Draw oval border Draw rectangular border Fill convex polygon with pattern Fill oval with pattern Fill pie slice with pattern Fill polygon with pattern Fill rectangle with pattern Fill oval frame with pattern Fill rectangular frame with pattern Draw line with pen and pattern Draw oval arc with pen and pattern Draw pie arc with pen and pattern Draw point with pen and pattern Draw polyline with pen and pattern Draw line with pen Draw oval arc with pen Draw pie arc with pen Draw point with pen Draw polyline with pen Assign value to pixel Fill region with color Fill region with pattern Draw styled line Draw styled oval Draw styled oval arc Draw styled pie arc 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 3.6.6 Poly Drawing Functions The TIGA communication driver functions pass the arguments of all the TIGA functions into a communication buffer for the TIGA graphics manager to use. Nearly all TIGA functions have fixed-size arguments that fit easily into the communication buffer. This is not the case with the poly drawing functions, shown in Table 3-9, which have a point list parameter that can be of any length. It is 3-15 Summary of Functions by Functional Group 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, against the communication buffer size in the CONFIG structure, or it can use alternate entry points (with an _a appended to the function name), which use a buffer allocated from the dynamic heap pool, to store the data. However, these alternate entry points are slower. Table 3-9.Poly Drawing Functions Function draw_polyline fill_convex fill_polygon patnfill_convex patnfill_polygon patnpen_polyline pen_polyline Description Draw polyline Draw solid convex polygon Fill polygon Pattern fill convex polygon Pattern fill polygon Pattern pen polyline Pen polyline Type Ext Ext Ext Ext Ext Ext Ext 3.6.7 Pixel Array Functions The pixel array functions, shown in Table 3-10, operate on rectangular pixel arrays. TIGA contains two bitmaps --the source and destination bitmaps-- used as implied operands for most of these functions. The source bitmap is ignored by all functions except bitblt, swap_bm, and zoom_rect. The destination bitmap is used as an implied operand for all drawing functions. If it is set to anything other than the screen, all drawing functions (other than bitblt) abort. In the future, linear drawing capability may be added to each drawing function to enable drawing into a linear bitmap. Table 3-10.Pixel Array Functions Function bitblt decode_rect encode_rect set_dstbm set_srcbm swap_bm zoom_rect Description Transfer bit-aligned block Decode rectangular image Encode rectangular image Set destination bitmap Set source bitmap Swap source and destination bitmaps Zoom source rectangle Type Ext Ext Ext Ext Ext Ext Ext 3-16 Application Interface Summary of Functions by Functional Group 3.6.8 Text Functions The text functions, shown in Table 3-11, provide the bitmap text-handling capabilities available in TIGA. Additional information concerning these capabilities can be found in Chapter 7, Bit-Mapped Text. Table 3-11. Text Functions Function delete_font get_fontinfo get_textattr get_text_xy in_font init_text install_font select_font set_textattr set_text_xy text_out text_outp text_width Description Remove a font from font table Return installed font information Return text-rendering attributes Return text x-y function Verify characters in font Initialize text-drawing environment Install font into font table Select an installed font Set text-rendering attributes Set text x-y position Render ASCII string Render ASCII string at current x-y position Return width of ASCII string Type Ext Core Ext Core Ext Core Ext Ext Ext Core Core Core Ext 3.6.9 Graphics Cursor Functions The graphics cursor functions, shown in Table 3-12, provide graphics cursor support. Consult the example program in the set_curs_shape function description in Chapter 4, page 4-103, for additional information. Table 3-12.Graphics Cursor Functions Function get_curs_state get_curs_xy set_curs_shape set_curs_state set_curs_xy set_cursattr Description Return current cursor state Return current cursor position Set current cursor shape Make cursor visible/invisible Set current cursor position Set current cursor attributes Type Core Core Core Core Core Core 3-17 Summary of Functions by Functional Group 3.6.10 Graphics Utility Functions The graphics utility functions, shown in Table 3-13, are a group of miscellaneous graphics functions, most of which require no explanation other than what is given with the individual functions. Table 3-13.Graphics Utility Functions Function cvxyl get_pixel get_wksp lmo peek_breg poke_breg rmo set_wksp Description Convert x-y address to linear address Return pixel value Return workspace information Return leftmost one bit number Read from B-file register Write to B-file register Return rightmost one bit number Set workspace information Type Core Ext Core Core Core Core Core Core 3.6.11 Handle-Based Memory Management Functions The handle-based memory management functions, shown in Table 3-14, provide TIGA with a handle-based memory management system. Handle-based memory management is preferred over pointer-based memory management because of its ability to reduce the amount of memory fragmentation. Memory fragmentation occurs when numerous allocations and deletions are made during an application. The fragmentation results in a reduction in the number of large, free memory blocks available to the application. 3-18 Application Interface Summary of Functions by Functional Group Table 3-14.Handle-Based Memory Management Functions Function gsph_alloc gsph_calloc gsph_compact gsph_deref gsph_falloc gsph_fcalloc gsph_findhandle gsph_findmem gsph_free gsph_init gsph_maxheap gsph_memtype gsph_realloc gsph_totalfree Description Allocate memory block Allocate and clear memory Invoke memory compaction routine Return pointer to memory block referenced by handle Allocate memory block with associated function Allocate and clear memory with associated function Return handle to specified memory address Return type of memory Free block of memory Initialize all user memory and compact all segments Return size of largest alloc without compaction Set characteristics of memory block Reallocate block of memory Return size of largest block with compaction Type Core Core Core Core Core Core Core Core Core Core Core Core Core Core 3.6.12 Pointer-Based Memory Management Functions The pointer-based memory management functions, shown in Table 3-15, provide TIGA with a pointer-based memory management system. The functions gsp_malloc, gsp_free, gsp_calloc, and gsp_realloc should be familiar to most C programmers. They operate in a manner similar to that of the memory management functions provided in the Microsoft C runtime library. Table 3-15.Pointer-Based Memory Management Functions Function get_offscreen_memory gsp_calloc gsp_free gsp_malloc gsp_maxheap gsp_minit gsp_realloc Description Return offscreen memory blocks Clear and allocate TMS340 memory Free TMS340 memory from allocation Allocate TMS340 memory Return largest free block Reinitialize dynamic memory pool Reallocate TMS340 memory Type Core Core Core Core Core Core Core 3-19 Summary of Functions by Functional Group 3.6.13 Data Input/Output Functions The data input/output functions, shown in Table 3-16, transfer data between host and TMS340 memory spaces, on between the TMS340 and its coprocessor. Table 3-16.Data Input/Output Functions Function cop2gsp field_extract field_insert gsp2cop gsp2gsp gsp2host gsp2hostxy host2gsp host2gspxy Description Copy from coprocessor memory to TMS340 memory Extract field from TMS340 memory Insert field into TMS340 memory Copy from TMS340 memory to coprocessor memory Transfer data within TMS340 memory Move data from TMS340 memory to host memory Copy rectangular memory area from TMS340 to host Move data from host memory to TMS340 memory Copy rectangular memory area from host to TMS340 Type Core Core Core Core Core Host Host Host Host 3.6.14 Extensibility Functions The extensibility functions, shown in Table 3-17, are described in detail in Chapter 8. Table 3-17.Extensibility Functions Function create_alm create_esym flush_esym flush_extended flush_module get_isr_priorities install_alm install_primitives install_rlm set_module_state sym_flush Description Create absolute load module Create external symbol table file Flush external symbol table file Flush all user extensions Remove module from TMS340 memory Return interrupt service routine priorities Install absolute load module Install extended drawing functions Install relocatable load module Set state of loaded module Flush relocatable load module symbols Type Host Host Host Host Core Core Host Host Host Core Core 3-20 Application Interface Summary of Functions by Functional Group 3.6.15 Interrupt Handler Functions The interrupt handler functions, shown in Table 3-18, provide interrupt handler support. For more information of interrupt handling in TIGA, refer to Section 8.9, Installing Interrupts, page 8-36. Table 3-18.Interrupt Handler Functions Function get_vector page_busy page_flip set_interrupt set_vector wait_scan Description Return address at TMS340 trap vector Return status of page flipping Flip display and drawing pages Set interrupt handler Set contents of TMS340 trap vector Wait for scan line Type Core Core Core Core Core Core 3-21 3-22 Application Interface Chapter 4 Core Functions This chapter discusses the core functions alphabetically. Each discussion Shows the syntax of the function declaration and the arguments that the function uses. Contains a description of the function operation, which explains input arguments and return values. Provides an example of the use of some functions. The examples in this chapter use the functions init_tiga and term_tiga to initialize and terminate the TIGA environment. Although the init_tiga and term_tiga functions are not actually TIGA functions, they do make calls to various TIGA functions. The init_tiga function initializes the TIGA environment and is called before any other TIGA function. The term_tiga function terminates a TIGA application by restoring the previous video mode and closing the TIGA communication driver. Refer to Section 3.4, page 3-6, for a sample TIGA application that illustrates the init_tiga and term_tiga functions. 4-1 Core Functions 4.1 Core Functions Reference The following is an alphabetical table of contents for functions reference. Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page aux_command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 clear_frame_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 clear_page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 clear_screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 cop2gsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 cpw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 create_alm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 create_esym . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 cvxyl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 field_extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17 field_insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18 flush_esym . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19 flush_extended . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20 flush_module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21 function_implemented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22 get_colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23 get_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24 get_curs_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26 get_curs_xy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27 get_fontinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28 get_isr_priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30 get_modeinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31 get_nearest_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34 get_offscreen_memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36 get_palet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38 get_palet_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40 get_pmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-42 get_ppop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43 get_text_xy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45 get_transp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46 get_vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-47 get_videomode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-48 get_windowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49 get_wksp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-50 gm_idlefunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-51 gsp2cop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52 gsp2gsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-53 gsp2host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54 gsp2hostxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55 gsp_calloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-56 gsp_execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57 gsp_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-58 gsp_malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-59 gsp_maxheap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60 gsp_minit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-61 gsp_realloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62 gsph_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-63 gsph_calloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64 gsph_compact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-65 gsph_deref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-66 gsph_falloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-67 gsph_fcalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68 gsph_findhandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69 gsph_findmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70 gsph_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-71 gsph_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-72 gsph_maxheap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-73 4-2 Core Functions Core Functions gsph_memtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-74 gsph_realloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-75 gsph_totalfree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-76 host2gsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-77 host2gspxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-78 init_palet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-79 init_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80 install_alm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-81 install_primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-82 install_rlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83 install_usererror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85 lmo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-87 loadcoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-88 page_busy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89 page_flip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-91 peek_breg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-93 poke_breg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-94 rmo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-95 set_bcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96 set_clip_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97 set_colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-99 set_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-100 set_curs_shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-103 set_curs_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-108 set_curs_xy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-109 set_cursattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-110 set_fcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-111 set_interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-112 set_module_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-113 set_palet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-115 set_palet_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-117 set_pmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-118 set_ppop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-120 set_text_xy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-122 set_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-123 set_transp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-124 set_vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-125 set_videomode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-126 set_windowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-128 set_wksp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-129 setup_hostcmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-130 sym_flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-131 synchronize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-132 text_out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-133 text_outp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-134 tiga_busy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-135 tiga_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-136 transp_off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-138 transp_on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-139 wait_scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-140 4-3 aux_command Execute Auxiliary Command Syntax #include Type Description Host-only The aux_command function invokes hardware-specific extended functions provided by the board OEM. Currently, two auxiliary commands are defined and callable on every TIGA-compliant board. Information pertaining to any additional auxiliary commands is supplied by the respective TIGA board manufacturer. The argument command_index specifies the auxiliary command to be executed. The argument command_buffer is a far pointer to arguments that may be required by the specified command. If no arguments are required, command_buffer is NULL. The format of the far pointer is dependent on the compiler being used, as follows: Compiler Microsoft MetaWare Microway Pointer Format DX = Segment, AX = Offset DX = Selector, EAX = Offset EAX = Selector :: 16 bit Offset For additional examples of correct far pointer handling, refer to the TEST_AUX example program for the various compilers in the \tiga\demos directory. Note: When the host PC is in protected mode, this command may pass back a data readable code selector as the 16 MSBs of the pointer. Any attempt to write to this segment results in a memory protection fault. Command indices 0 - 99 are reserved for the exclusive use of Texas Instruments. Command indices 100 - 65535 are available for OEM use. The following command indices have been defined and are supported on all TIGA compliant boards: command_index = 0, command_buffer = NULL Auxiliary command 0 with a NULL command_buffer pointer returns a far pointer to a null terminated string identifying the TMS340-based board on which the TIGA driver is operating. A null pointer may be returned by this command. 4-4 Core Functions Execute Auxiliary Command aux_command command_index = 1, command_buffer = NULL Auxiliary command 1 with a NULL command_buffer pointer returns a far pointer to the following AUX_CONFIG structure: typedef struct { unsigned long unsigned long }MEM_MAP; typedef struct { unsigned short unsigned short }IO_MAP; typedef struct { unsigned short unsigned short short MEM_MAP short IO_MAP }AUX_CONFIG; base; range; base; range; alt_video; emulation; mem_mapped; memmap[8]; io_mapped; iomap[8]; The fields of the MEM_MAP structure are defined as follows: base A 32-bit field that specifies the paragraph address corresponding to the start of the memory-mapped host area. For example, an origin value of D700 specifies the actual address of D700:0 or D7000. A 32-bit field that specifies the size in bytes, of the memorymapped area, beginning at the paragraph address specified by the origin. range The fields of the IO_MAP structure are defined as follows: base range A 16-bit field that specifies the starting I/O address of a range I/O address. A 16-bit field that specifies the range, in bytes, of the I/Omapped area beginning at the I/O address specified by base. For example, a base address of 0x280 with range of 0x10 specifies the I/O address of 0x280 to 0x290. The fields of the AUX_CONFIG structure are defined as follows: alt_video Alternate video capabilities. This 16-bit field describes the alternate non-TMS340 video capabilities of the TMS340-based board. MDA capability (0=no / 1=yes) CGA capability (0=no / 1=yes) Bits 0 Bits 1 4-5 aux_command Execute Auxiliary Command Bits Bits Bits Bits Bits Bit Bits 2 3 4 5 6-12 13 14-15 HERC capability (0=no / 1=yes) EGA capability (0=no / 1=yes) VGA capability (0=no / 1=yes) 8514/A capability (0=no / 1=yes) Reserved Shared VRAM buffer (0=no / 1=yes) Monitor config (00=Single / 01=Dual) Capability is defined as the ability of the TMS340-based board to display output in the indicated format, either through onboard chip support, pass-through, or TMS340 software emulation. emulation Alternate video emulation flags. This 16-bit field tells whether the capabilities described in the alt_video field are emulated in software by the TMS340 processor. MDA emulated (0=no / 1=yes) CGA emulated (0=no / 1=yes) HERC emulated (0=no / 1=yes) EGA emulated (0=no / 1=yes) VGA emulated (0=no / 1=yes) 8514/A emulated (0=no / 1=yes) Reserved Bits Bits Bits Bits Bits Bits Bits 0 1 2 3 4 5 6-15 Emulation is defined as the entire or partial support that the TMS340 provides through software emulation, processor of the indicated video format. Emulation also indicates that the alternate video mode and TIGA modes share the same video buffer and/or program RAM area. mem_mapped A16-bit field that specifies the number of memory-mapped host address areas used by the board. memmap An array structure of type MEM_MAP, containing the base address and range of each memory-mapped area. The number of areas is specified by the mem_mapped field. A 16-bit field that specifies the number of I/O-mapped host address areas used by the board. An array of structure of type IO_MAP, containing the base address and range of each I/O-mapped area. The number of areas is specified by the io_mapped field. io_mapped iomap 4-6 Core Functions Clear Frame Buffer clear_frame_buffer Syntax #include /* pixel value */ Type Description Core The clear_frame_buffer function rapidly clears the entire display memory by setting it to the specified color. If the display memory contains multiple display pages (for example, for double-buffered animation), all pages are cleared. Argument color is a pixel value. Given a screen pixel depth of N bits, the pixel value contained in the N LSBs of the argument is replicated throughout the display memory. In other words, the pixel value is replicated 32/N times within each 32-bit longword in the display memory. Pixel size N is restricted to the values 1, 2, 4, 8, 16, and 32 bits. If the value of argument color is specified as -1, the function clears the display memory to the current background color. (To clear the frame buffer to all 1s when the pixel size is 32 bits, set the background color to 0xFFFFFFFF and call the clear_frame_buffer function with an argument of -1.) This function can rapidly clear the screen in hardware configurations that support bulk initialization of the display memory. Bulk initialization is supported by video RAMs that can perform serial-register-to-memory cycles. The serial register in each video RAM is loaded with initialization data and copied internally to a series of rows in the memory array. Whether the function utilizes bulk initialization or some other functionally equivalent method of clearing the screen varies from one implementation to the next. Offscreen areas of the display memory may also be affected by this function; data stored in such areas may be lost as a result. The clear_screen function is similar in operation but does not affect data contained in offscreen areas. If the graphics display system reserves an area of the display memory to store palette information (as is the case in configurations that use the TMS34070 color palette chip), this area is left intact by the function. Example Use the clear_frame_buffer function to clear the display memory to the default background color. Use the text_out function to print a couple of words to the screen. #include 4-7 clear_page Clear Current Drawing Page Syntax #include /* pixel value */ Type Description Core The clear_page function rapidly clears the entire drawing page by setting it to the specified pixel value. If the display memory contains multiple display pages (for example, for double-buffered animation), only the current drawing page is cleared. Given a screen pixel depth of N bits, the pixel value contained in the N LSBs of argument color is replicated throughout the drawing page memory. In other words, the pixel value is replicated 32/N times within each 32-bit long word in the area of display memory corresponding to the page. Pixel size N is restricted to the values 1, 2, 4, 8, 16, and 32 bits. If the value of argument color is specified as -1, the function clears the page to the current background color. (In order to clear the drawing page to all 1s when the pixel size is 32 bits, set the background color to 0xFFFFFFFF and call the clear_page function with an argument of -1.) The clear_page function can rapidly clear the screen in hardware configurations that support bulk initialization of the display memory. Bulk initialization is supported by video RAMs that can perform serial-register-to-memory cycles. The serial register in each video RAM is loaded with initialization data and copied internally to a series of rows in the memory array. Whether the function utilizes bulk initialization or some other functionally equivalent method of clearing the screen varies from one implementation to the next. The clear_page function can affect offscreen as well as onscreen areas of the display memory. Data stored in offscreen areas may be lost as a result. The clear_screen function is similar in operation but does not affect data contained in offscreen areas. The clear_page function may clear the screen more rapidly than the clear_screen function, depending on the implementation. If the graphics display system reserves an area of the display memory to store palette information (as is the case in configurations that use the TMS34070 color palette chip), this area is left intact by the function. Example Use the clear_page function to clear alternating drawing pages in an application requiring double-buffered animation. The current graphics mode is assumed to support more than one video page. The text_out function is used to make the letters abc rotate in a clockwise direction around the digits 123. Core Functions 4-8 Clear Current Drawing Page clear_page #include main() { long x, y; short disppage, drawpage; init_tiga(0); drawpage = 0; disppage = 1; x = (long)RADIUS << 16; y = 0; do { page_flip(disppage ^= 1, drawpage^= 1); x -= y >> 5; y += x >> 5; while(page_busy()); clear_page(-1); text_out(RADIUS,RADIUS,"123"); text_out(RADIUS+(x>>16), RADIUS+(y>>16), "abc"); }while(!kbhit()); getch(); term_tiga(); } 4-9 clear_screen Clear Screen Syntax #include /* pixel value */ Type Description Core The clear_screen function clears the entire current drawing page by setting it to the specified pixel value. If the display memory contains multiple display pages (for example, for double-buffered animation), only the current drawing page is cleared. Given a screen pixel depth of N bits, the pixel value contained in the N LSBs of argument color is replicated throughout the visible screen memory. In other words, the pixel value is replicated 32/N times within each 32-bit long word in the area of display memory corresponding to the visible screen. Pixel size N is restricted to the values 1, 2, 4, 8, 16, and 32 bits. If the value of argument color is specified as -1, the function clears the screen to the current background color. (To clear the screen to all 1s when the pixel size is 32 bits, set the background color to 0xFFFFFFFF and call the clear_screen function with an argument of -1.) The clear_screen function does not affect data contained in offscreen areas of the display memory. The clear_page function is similar in operation but may affect data contained in offscreen areas; data stored in such areas may be lost as a result. The clear_page function may clear the screen more rapidly than the clear_screen function, depending on the implementation. Example Use the clear_screen function to clear the screen to the default background color before printing the text "Hello world" on the screen. #include 4-10 Core Functions Copy From Coprocessor Memory to TMS340 Memory cop2gsp Syntax #include Type Description Core The cop2gsp function copies data from the address space of the TMS34082 coprocessor with id copid (a number from 0 to 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. 4-11 cpw Compare Point to Clipping Window Syntax #include /* pixel coordinates */ Type Description Core The cpw function returns a 4-bit outcode indicating the specified pixel's position relative to the current clipping window. The outcode indicates whether the pixel is located above or below, to the left or right of, or inside the clipping window. Arguments x and y are the coordinates of the pixel, specified relative to the current drawing origin. The clipping window is rectangular. As shown in Figure 4-1, the area surrounding the clipping window is partitioned into 8 regions. Figure 4-1. Outcodes for Lines Endpoints +x 0101 0100 0110 +y Y=Y Min. 0001 0000 0010 Y=Y Max. Window 1001 X=X Min. 1000 1010 X=X Max. Each of the 8 regions is identified by a unique 4-bit outcode. The outcode values for the 8 regions and for the window itself are encoded as follows: 01XX2 10XX2 XX012 XX102 00002 if the point lies above the window if the point lies below the window if the point lies left of the window if the point lies right of the window if the point lies within the window The outcode is right-justified in the 4 LSBs of the return value and zero-extended. 4-12 Core Functions Compare Point to Clipping Window cpw Refer to the user's guide for the TMS34010 or TMS34020 for a detailed description of the outcodes. Example Use the cpw function to animate a moving object that bounces off the sides of the clipping window. When a check of the object's x-y coordinates indicates that it has strayed outside the window, the sign of the object's x or y component of velocity, as appropriate, is reversed. The moving object is an asterisk rendered in the system font. The asterisk is erased by overwriting it with a blank. Note that the system font is a block font; overwriting an asterisk with a blank from a proportionally spaced font might not have the same effect. #include 4-13 create_alm Create Absolute Load Module Syntax #include Type Description Host-only The create_alm function creates an Absolute Load Module (ALM). ALMs were required before version 2.0 of TIGA because the downloading of a user extension to TIGA was done by calling the linking loader. This is not the case in versions 2.0 onward, so ALMs are now redundant. This function is included purely to maintain compatibility with TIGA drivers written before version 2.0 of TIGA. The create_alm function converts the relocatable load module (specified by rlm_name) into an absolute load module and saves it under the filename specified by alm_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 -l option of 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 subsection 8.3.2. If the function terminates correctly, zero is returned; if an error occurs, a negative error code is returned. The function returns these error codes: Error Code -3 -6 Description Out of Memory -- Not enough TMS340 memory to load the ALM. Error Accessing RLM -- Unable to open RLM for reading. Either the spelling of the RLM filename does not match the RLM filename in the current directory, or the -l option of the TIGA environment variable is not set up correctly. Error Accessing ALM -- Unable to open ALM for writing; check the specified file name. Symbol Reference -- An unresolved symbol was refernced by the RLM. Determine the name of the symbol, either by producing a link map for the RLM or by invoking TIGALNK from the command line via the -ec option. Error Loading COFF File -- An error was obtained in the loading of the COFF file. Recreate the RLM and try again. Out of Symbol Memory -- Not enough TMS340 memory to store the symbols of the RLM. Core Functions -8 -10 -14 -15 4-14 Create External Symbol Table create_esym Syntax Type Description short create_esym() Host-only The create_esym function does not need to be called. It is provided for downward compatibility with prior versions of TIGA, which provided stored symbol table information in a host file. This function creates a new symbol table in TMS340 memory. After creation, the table contains only the global (or external) symbols that were contained in the TIGA graphics manager file. During subsequent installations of relocatable load modules, this table is used to resolve external references. Also, any external symbols contained in the RLM are added to table during the installation process so that those symbols can be referenced by other RLMs. The symbol table is flushed automatically at the start of each application or you can do it explicitly by calling the flush_esym or the flush_extended functions. For more details on extensibility, refer to Chapter 8. If an error occurs, a negative error code is returned. If the function terminates normally, zero is returned. This function can return the following error codes: Error Code -3 -9 Description Out of Memory -- Not enough TMS340 memory to create the symbol table. Error Accessing TIGAGM.OUT -- Could not access the graphics manager COFF file to read in the symbols. The file is either missing, or the -m option of the TIGA environment variable is not set up correctly. Error Loading COFF File -- An error was obtained in the load of the tigagm.out COFF file. Recopy this file from the installation disk. Out of Symbol Memory -- Not enough TMS340 memory to store the symbol table. -14 -15 4-15 cvxyl Convert x-y Position to Linear Address Syntax #include /* x-y coordinates */ Type Description Core The cvxyl function returns the 32-bit linear address of a pixel in the TMS340 graphics processor's memory, given the x and y coordinates of the pixel on the screen. Arguments x and y are the coordinates of the specified pixel, defined relative to the current drawing origin. If the coordinates correspond to an offscreen location, the calling program is responsible for ensuring that the coordinates correspond to a valid pixel location. Example Use the cvxyl function to determine the base addresses of the all the video pages available in the current graphics mode. The page_flip function is used repeatedly to flip to a new page before the cvxyl function is called. The text_out function is used to print out the 32-bit memory address of each page. #include 4-16 Core Functions Extract Field From TMS340 Memory field_extract Syntax #include */ */ Type Description Core The field_extract function returns the contents of a field located in TMS340 memory. Argument gptr is a pointer containing the 32-bit address of a field in the TMS340 graphics processor's memory. Argument fs specifies the length of the field and is restricted to values in the range of 1 to 32 bits. The function definition places no restrictions on the alignment of the address; the field is permitted to begin at any bit address. Given an fs value of N and a gptr value of A, the specified field consists of contiguous bits A through A+N-1 in memory. The contents of the field are placed in the N LSBs of the return value and zeroextended. Example Use the field_extract function to examine a field from an I/O register located in the TMS340 graphics processor's memory. Retrieve the contents of the PPOP field, a 5-bit field that begins in bit 10 of the CONTROL register. #include */ */ */ 4-17 field_insert Insert Field Into TMS340Memory Syntax #include */ */ */ Type Description Core The field_insert function writes a specified value to a field located in the TMS340 graphics processor's memory. Argument gptr is a pointer containing the 32-bit address of a field in the TMS340 graphics processor's memory. Argument fs specifies the length of the field and is restricted to values in the range of 1 to 32 bits. Argument val specifies the value to be written. The function definition places no restrictions on the alignment of the address; the field is permitted to begin at any bit address. Given an fs value of N and a gptr value of A, the specified field consists of contiguous bits A through A+N-1 in memory. The N LSBs of argument val are copied into the specified field in memory; the remaining bits of the argument are ignored by the function. Example Use the field_insert function to load a value into a field in an I/O register located in the TMS340 graphics processor's memory. The PPOP field is a 5-bit field that begins in bit 10 of the CONTROL register. Use the get_ppop function to read back the PPOP field, and use the text_out function to print its value. #include */ */ 4-18 Core Functions Flush External Symbol Table File flush_esym Syntax #include Type Description Host-only The flush_esym function does not need to be called by the user. It is provided for backwards compatibility with older versions of TIGA, which provided stored symbol table information in a host file. This function deletes all unsecured installed modules and flushes the module symbols from the symbol table, except for those in the TIGA graphics manager. Currently, there are no error codes returned by this function. For more details on extensibility, refer to Chapter 8. 4-19 flush_extended Flush All User Extensions Syntax #include Type Description Host-only The flush_extended function deletes all unsecured installed modules and flushes the module symbols from the symbol table, except for those in the TIGA graphics manager. Note that if TIGA is initialized with a call to set_videomode with an INIT style parameter, this function is executed automatically because all unsecured heap is initialized. For more details on extensibility and the use of this function, see Chapter 8. 4-20 Core Functions Remove Module From TMS340 Memory flush_module Syntax #include */ Type Description Host-only The flush_module function flushes the code and symbols of the module specified by the argument module_id, which is returned by the install_rlm and install_alm functions. Use the constant GRAPHICS_LIB_ID defined in the tiga.h file to specify the module corresponding to the extended graphics library module. The function returns the following values: 1 = Module flushed succesfully 0 = Error, caused by one of the following: Invalid module id Specified module is not loaded Specified module is locked 4-21 function_implemented Return if Function Is Implemented Syntax #include Type Description Host-only The function_implemented function queries whether a function is implemented or not. Functions in TIGA have an associated function_code; some functions 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 set_palet get_palet set_palet_entry get_palet_entry set_transp gsp2cop init_palet The function codes themselves are contained in the tiga.h, tiga.hch, and tiga.ndp include files, which contain 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)) { ..... } Example #include Core Functions Return Foreground and Background Colors get_colors Syntax #include /* pointer to foreground color /* pointer to background color */ */ Type Description Core The get_colors function retrieves the pixel values corresponding to the current foreground and background colors. Arguments fcolor and bcolor are pointers to long integers into which the function loads the foreground and background colors, respectively. Each pixel value is right-justified within its destination longword and is zero-extended. Example Use the get_colors function to retrieve the default foreground and background pixel values. Use the text_out function to print the values on the screen. #include main() { FONTINFO fontinfo; unsigned long fcolor, bcolor; short x, y; char s[20]; init_tiga(0); clear_screen(-1); get_fontinfo(0, &fontinfo); get_colors(&fcolor, &bcolor); /* retrieve colors x = y = 10; sprintf(s, "white = %ld", fcolor); text_out(x, y, s); y += fontinfo.charhigh; sprintf(s, "black = %ld", bcolor); text_out(x, y, s); term_tiga(); } */ 4-23 get_config Return Hardware Configuration Information Syntax #include /* hardware configuration info */ Type Description Core The get_config function retrieves a list of parameters that describe the characteristics of both the hardware configuration and the current graphics mode. Argument config is a pointer to a structure of type CONFIG, into which the function copies parameter values describing the configuration of the display hardware. The last field in the CONFIG structure is a structure of type MODEINFO that contains parameters describing the currently selected graphics mode. The CONFIG structure contains the following fields: typedef struct { unsigned short unsigned long unsigned long unsigned long unsigned short unsigned short unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long HPTR PTR MODEINFO }CONFIG; version_number; comm_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; 4-24 Core Functions Return Hardware Configuration Information get_config The MODEINFO structure contains the following fields: typedef struct { unsigned long unsigned short unsigned short short short unsigned short unsigned long unsigned short unsigned long short unsigned short short unsigned long unsigned long unsigned short unsigned short unsigned long unsigned long unsigned long unsigned short unsigned short unsigned short }MODEINFO; disp_pitch; disp_vres; disp_hres; screen_wide; screen_high; disp_psize; pixel_mask; palet_gun_depth; palet_size; palet_inset; num_pages; num_offscrn_areas; wksp_addr; wksp_pitch; silicon_capability; color_class; red_mask; blue_mask; green_mask; x_aspect; y_aspect; diagonal_aspect; Refer to the CONFIG and MODEINFO structure descriptions in Appendix A for detailed descriptions of each field. Note that the CONFIG and MODEINFO structures may change in subsequent revisions. To minimize the impact of such changes, write your application programs to refer to the elements of the structure symbolically by their field names, rather than as offsets from the start of the structure. The include files provided with the library will be updated in future revisions to track any such changes in data structure definitions. Example Use the get_config function to retrieve the pixel size for the current graphics mode. Use the text_out function to print the pixel size on the screen. #include 4-25 get_curs_state Return Current Cursor State Syntax #include Type Description Example Core The get_curs_state function returns true (nonzero) if the graphics cursor is enabled, false (zero) otherwise. See cursor manipulation in set_curs_shape. 4-26 Core Functions Return Current Cursor Position get_curs_xy Syntax #include Type Description Core The get_curs_xy returns the pixel coordinates of the graphics cursor hotspot. Note that the coordinates are relative to the upper left corner of the screen, not to the drawing origin. Note: Because the cursor is moved by an interrupt service routine driven by the display interrupt of the TMS340 processor, it is possible to set a new position and then execute a get_curs_xy to return this new position before the interrupt service routine has actually moved the cursor. Thus, the function returns the new position either where the cursor is, if the display interrupt has been invoked, or where it will be, once the display interrupt has been invoked for the current frame. Example See cursor manipulation in set_curs_shape. 4-27 get_fontinfo Return Installed Font Information Syntax #include */ */ Type Description Core The get_fontinfo function copies a structure whose elements describe the characteristics of the designated font. The font must have been previously installed in the font table. Argument id is an index that identifies the font. The system font is always designated as font 0; that is, it is identified by an id value of 0. The system font is installed in the font table during initialization of the drawing environment by TIGA. Additional fonts may be installed in the font table by means of calls to the install_font function. The install_font function returns an identifier value that is subsequently used to refer to the font. The currently selected font is designated by an id value of -1. Argument pfontinfo is a pointer to a structure of type FONTINFO, into which the function copies parameter values that characterize the font designated by argument id. The function returns a nonzero value if the structure is successfully copied; otherwise, it rerutns 0. The FONTINFO structure contains the following fields: typedef struct { char facename[30]; short deflt; short first; short last; short maxwide; short avgwide; short maxkern; short charwide; short charhigh; short ascent; short descent; short leading; PTR fontptr; short id; }FONTINFO; Refer to the FONTINFO structure description in appendix A for detailed descriptions of each field. 4-28 Core Functions Return Installed Font Information get_fontinfo Note that the FONTINFO structure may change in subsequent revisions. To minimize the impact of such changes, write your application programs to refer to the elements of the structure symbolically by their field names, rather than as offsets from the start of the structure. The include files provided with the library will be updated in future revisions to track any such changes in data structure definitions. Example Use the get_fontinfo function to retrieve the face name, character width, and character height of the system font. Use the text_out function to display the three font parameters on the screen. #include 4-29 get_isr_priorities Return Interrupt Service Routine Priorities Syntax #include */ */ Type Description Core The get_isr_priorities function returns the priorities assigned when installing interrupt service routines (ISRs) using the install_rlm or install_alm 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 this function is called, all priority data is flushed internally within TIGA, thereby enabling new priority data to be collected the next time install_alm or install_rlm is called to install an ISR. For more details on extensibility and the use of this function, see Chapter 8. 4-30 Core Functions Return Graphics Mode Information get_modeinfo Syntax #include */ */ Type Description Host-only The get_modeinfo function copies a structure whose elements describe the characteristics of the designated graphics mode. Argument index is a number that identifies one of the graphics modes supported by the display hardware configuration. The index values are assigned to the available graphics modes by the display hardware vendor. Each configuration supports one or more graphics modes, which are numbered in ascending order beginning with 0. Argument modeinfo is a pointer to a structure of type MODEINFO, into which the function copies parameter values that characterize the graphics mode designated by argument index. The function returns a nonzero value if the mode information is successfully retrieved. If an invalid index is specified, the function returns 0. The number of graphics modes supported by a particular display configuration is specified in the num_modes field of the CONFIG structure returned by the get_config function. Given that the number of supported modes is some number N, the modes are assigned indices from 0 to N-1. The get_modeinfo function has no effect on the current graphics mode setting. The display is configured in a particular graphics mode by means of a call to the set_config function. 4-31 get_modeinfo Return Graphics Mode Information The MODEINFO structure contains the following fields: typedef struct { unsigned long unsigned short unsigned short short short unsigned short unsigned long unsigned short unsigned long short unsigned short short unsigned long unsigned long unsigned short unsigned short unsigned long unsigned long unsigned long unsigned short unsigned short unsigned short }MODEINFO; disp_pitch; disp_vres; disp_hres; screen_wide; screen_high; disp_psize; pixel_mask; palet_gun_depth; palet_size; palet_inset; num_pages; num_offscrn_areas; wksp_addr; wksp_pitch; silicon_capability; color_class; red_mask; blue_mask; green_mask; x_aspect; y_aspect; diagonal_aspect; Refer to the MODEINFO structure description in Appendix A for detailed descriptions of each field. Note that the MODEINFO structure may change in subsequent revisions. To minimize the impact of such changes, write your application programs to refer to the elements of the structure symbolically by their field names, rather than as offsets from the start of the structure. The include files provided with the library will be updated in future revisions to track any such changes in data structure definitions. Example Use the get_modeinfo function to retrieve a list of the screen resolutions corresponding to the graphics modes supported by the display hardware configuration. Use the text_out function to print the list on the screen. 4-32 Core Functions Return Graphics Mode Information get_modeinfo #include /* MODEINFO, CONFIG & FONTINFO */ init_tiga(0); clear_screen(-1); get_fontinfo(0, &fntinf); x = y = 10; for (mode = 0; get_modeinfo(mode, &modinf); mode++) { sprinf(s, "mode = %d: %d-by-%d", mode, modinf.disp_hres, modinf.disp_vres); text_out(x, y, s); y += fntinf.charhigh; } term_tiga(); } 4-33 get_nearest_color Return Nearest Color in Palette Syntax #include */ */ Type Description Core The get_nearest_color function returns the pixel value whose color is closest to that specified by the input arguments. If the current graphics mode supports a color display, arguments r, g, and b represent the 8-bit red, green, and blue components of the target color. Each component value corresponds to an intensity value in the range 0 to 255, where 255 is the brightest intensity and 0 is the darkest. In the case of a gray-scale display, argument i represents a gray-scale intensity in the range of 0 to 255. The pixel value returned by the function is right-justified and zero-extended. In the case of a gray-scale palette, the return value is the pixel whose intensity is closest to that specified in argument i. In the case of a color palette, the function performs a more complex calculation. The function calculates the magnitude of the differences between the r, g, and b argument values and the red, green, and blue components, respectively, of each individual color available in the palette. Each of the three differences (red, green, and blue) is multiplied by an individual weighting factor, and the sum of the weighted differences is treated as the effective distance of the color palette entry from the color specified by arguments r, g, and b. The palette entry corresponding to the smallest weighted sum is selected as being nearest to the specified color. The function returns the palette index value corresponding to the selected color. Example Use the get_nearest_color function to determine the pixel values around the perimeter of a color wheel. Use the fill_piearc function from the extended functions library to render the wheel. The wheel is partitioned into the following six regions of color transition: red to yellow yellow to green green to cyan cyan to blue blue to magenta magenta to red Each region spans a 60-degree arc of the wheel. 4-34 Core Functions Return Nearest Color in Palette get_nearest_color #include t < 60; t++, g += 4) /* red to yellow /* yellow to green /* green to cyan /* cyan to blue /* blue to magenta /* magenta to red */ */ */ */ */ */ 4-35 get_offscreen_memory Return Offscreen Memory Blocks Syntax #include */ Type Description Core The get_offscreen_memory function returns a list of offscreen buffers located in the TMS340 graphics processor's display memory. Argument num_blocks specifies the number of offscreen buffer areas to be listed. Argument offscreen is an array to contain the list of offscreen buffers. Each element of the offscreen array is a structure of type OFFSCREEN_AREA. The OFFSCREEN_AREA structure contains the following fields: typedef struct { PTR addr; unsigned short xext; unsigned short yext; }OFFSCREEN_AREA; Refer to the OFFSCREEN_AREA structure description in Appendix A for detailed descriptions of each field. An offscreen buffer is a two-dimensional array of pixels, the rows of which may not be contiguous in memory. The pixel size is the same as that of the screen, and each offscreen buffer has the same pitch as the screen. The pitch is the difference in memory addresses between two vertically adjacent pixels in the buffer. If an offscreen buffer is used as the offscreen workspace (see the description of the set_wksp and get_wksp functions), this buffer is always the first buffer listed in the offscreen array. Let N represent the number of offscreen buffers available in a particular graphics mode. If argument num_blocks is greater than N, only the first N elements of the offscreen array will be loaded with valid data. If argument num_blocks is less than N, only the first num_blocks elements of the offscreen array will be loaded with valid data. The number of offscreen areas available in the current mode is specified in the num_offscrn_areas field of the CONFIG structure returned by the get_config function. After the display memory (usually video RAM) has been partitioned into one or more video pages (or frame buffers), some number of rectangular, noncontiguous blocks of display memory are typically left over. These blocks may not be suitable for general use (for example, for storing a program) but may be of use to some applications as temporary storage for graphical information such as the areas behind pull-down menus on the screen. 4-36 Core Functions Return Offscreen Memory Blocks get_offscreen_memory Example Use the get_offscreen_memory function to list the first (up to) 5 offscreen buffers available in the current graphics mode. Use the text_out function to print on the screen the x and y extent of each buffer . #include 4-37 get_palet Read Entire Palette Syntax #include */ */ Type Description Core The get_palet function copies multiple palette entries into an array. Argument palet_size is the number of palette entries to load into the target array. Argument palet is an array of type PALET. The PALET structure contains the following fields: typedef struct { unsigned char unsigned char unsigned char unsigned char }PALET; r; g; b; i; Refer to the PALET structure description in Appendix A for detailed descriptions of each field. Each array element is a structure containing r, g, b, and i fields. Each field specifies an 8-bit red, green, blue, or gray-scale intensity value in the range of 0 to 255, where 255 is the brightest intensity and 0 is the darkest. In the case of a graphics mode for a color display, the red, green, and blue component intensities are loaded into the r, g, and b fields, respectively, while the i field is set to 0. In the case of a gray-scale mode, the intensities are loaded into the i fields, and the r, g, and b fields are set to 0. If argument palet_size specifies some number N that is less than the number of entries in the palette, only the first N palette entries are loaded into the array. If the number N of palette entries is less than the number specified in palet_size, only the first N elements of the array are modified. The number of palette entries in the current graphics mode is specified in the palet_size field of the CONFIG structure returned by the get_config function. The 8-bit r, g, b, and i values retrieved for each palette entry represent the color components or gray-scale intensity actually output by the physical display device. For example, assume that the r, g, b, and i values of a particular palette entry are set by the set_palet or set_palet_entry functions to the following values: r = 0xFF, g = 0xFF, b = 0xFF, and i = 0. If the display hardware supports only 4 bits of red, green, and blue intensity per gun, the values read by a call to get_palet or get_palet_entry are r = 0xF0, g = 0xF0, b = 0xF0, and i = 0. Example Use the get_palet function to get the r, g, b, and i components of the first 8 colors in the default palette. Use the text_out function to print the values on the screen. Core Functions 4-38 Read Entire Palette get_palet #include /* PALET, CONFIG and FONTINFO /* max. LUT entries to print */ */ init_tiga(0); clear_screen(-1); get_config(&cfg); if ((size = cfg.mode.palet_size) > MAXSIZE) size = MAXSIZE; get_palet(size, lut); /* get up to 8 palette entries get_fontinfo(-1, &fntinf); x = y = 10; for (k = 0; k < size; k++, y += fntinf.charhigh) { sprintf(s, "Color %d: r = %d, g = %d, b = %d, i = %d", k, lut[k].r, lut[k].g, lut[k].b, lut[k].i); text_out(x, y, s); } term_tiga(); } */ 4-39 get_palet_entry Return Single Palette Entry Syntax #include */ */ */ Type Description Core The get_palet_entry function returns the red, green, blue, and gray-scale intensity components of a specified entry in the palette. The palette entry is specified by argument index, which is an index into the color lookup table, or palette. If the palette contains N entries, valid indices are in the range 0 to N-1. The number of palette entries in the current graphics mode is specified in the palet_size field of the CONFIG structure returned by the get_config function. Arguments r, g, b, and i are pointers to the red, green, blue, and gray-scale intensity values, respectively, that are retrieved by the function. Each intensity is represented as an 8-bit value in the range of 0 to 255, where 255 is the brightest intensity and 0 is the darkest. In the case of a graphics mode for a color display, the red, green, and blue component intensities are loaded into the r, g, and b fields, respectively, while the i field is set to 0. In the case of a gray-scale mode, the intensity is loaded into the i field, and the r, g, and b fields are set to 0. If argument index is in the valid range, the function returns a nonzero value, indicating that the components of the palette entry have been successfully retrieved. If argument index is invalid, the return value is 0, indicating that no palette entry corresponds to the specified index. Example Use the get_palet_entry function to get the r, g, b, and i components of the first 8 colors in the default palette. Use the text_out function to print the values on the screen. 4-40 Core Functions Return Single Palette Entry get_palet_entry #include */ */ 4-41 get_pmask Return Plane Mask Syntax #include Type Description Core The get_pmask function returns the value of the plane mask. The size of the plane mask in bits is the same as the pixel size. Given a pixel size of N bits, the plane mask is right-justified in the N LSBs of the return value and is zero-extended. The screen pixel size in the current graphics mode is specified in the disp_psize field of the CONFIG structure returned by the get_config function. The plane mask designates which bits within a pixel are protected against writes and affects all operations on pixels. During writes, the 1s in the plane mask designate bits in the destination pixel that are protected against modification, while the 0s in the plane mask designate bits that can be altered. During reads, the 1s in the plane mask designate bits in the source pixel that are read as 0s, while the 0s in the plane mask designate bits that can be read from the source pixel as is. The plane mask is set to its default value of 0 during initialization of the drawing environment. The plane mask can be altered with a call to the set_pmask function. The plane mask corresponds to the contents of the TMS340 graphics processor's PMASK register. The effect of the plane mask in conjunction with the pixel-processing operation and the transparency mode is described in the user's guides for the TMS34010 and TMS34020. Example Use the get_pmask function to verify that the plane mask is initialized to 0. Use the text_out function to print the default plane mask value to the screen. #include 4-42 Core Functions Return Pixel-Processing Operation Code get_ppop Syntax #include Type Description Core The get_ppop function returns the pixel-processing operation code. The 5-bit PPOP code determines the manner in which pixels are combined (Boolean or arithmetic operation) during drawing operations. The PPOP code is right-justified in the 5 LSBs of the return value and is zeroextended. Legal PPOP codes are in the range of 0 to 21. The source and destination pixel values are combined according to the selected Boolean or arithmetic operation, and the result is written back to the destination pixel. As shown in Table 4-1, Boolean operations are in the range of 0 to 15, and arithmetic operations are in the range of 16 to 21. Table 4-1.Pixel-Processing Operations PPOP Code 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 Description replace destination with source source AND destination source AND NOT destination set destination to all 0s source OR NOT destination source EQU destination NOT destination source NOR destination source OR destination destination (no change) source XOR destination NOT source AND destination set destination to all 1s NOT source or destination source NAND destination NOT source source plus destination (with overflow) source plus destination (with saturation) destination minus source (with overflow) destination minus source (with saturation) MAX(source, destination) MIN(source, destination) The PPOP code is set to its default value of 0 (replace operation) during initialization of the drawing environment. The PPOP code can be altered with a call to the set_ppop function. The pixel-processing operation code corresponds to the 5-bit PPOP field in the TMS340 graphics processor's CONTROL register. The effects of the 22 different codes are described in more detail in the user's guides for the TMS34010 and TMS34020. Example Use the get_ppop function to verify that the pixel-processing operation code is initialized to 0 (replace destination with source). Use the text_out function to print the default PPOP code to the screen. 4-43 #include 4-44 Core Functions Return Text x-y Position get_text_xy Syntax #include /* text x-y coordinates */ Type Description Core The get_text_xy function retrieves the x-y coordinates of the current text drawing position. This is the position at which the next character (or string of characters) will be drawn if a subsequent call is made to the text_outp function. Both the text_outp and text_out functions automatically update the text position to be the right edge of the last string output to the screen. Arguments x and y are pointers to variables of type short. The x and y coordinate values copied by the function into these variables correspond to the current text position on the screen, specified relative to the current drawing origin. The x coordinate corresponds to the left edge of the next string output by the text_outp function. The y coordinate corresponds either to the top of the string or to the base line, depending on the state of the text alignment attribute (see the description of the set_textattr function). Example Use the get_text_xy function to print four short lines of text in a stairstep pattern on the screen. Each time the text_outp function outputs the string step to the screen, the get_text_xy function is called next to obtain the current text position. The y coordinate of this position is incremented by a call to the set_text_xy function, and the next call to the text_outp function prints the string at the new position. #include 4-45 get_transp Return Transparency Flag Syntax #include Type Description Core The get_transp function returns a value indicating whether transparency is enabled. A nonzero value is returned if transparency is enabled; 0 is returned if transparency is disabled. Transparency is an attribute that affects drawing operations. 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 on the TMS34010, and is modified according to the transparency mode selected on the TMS34020. To avoid modifying destination pixels in the rectangular region surrounding each character shape, transparency can be enabled before the text_out or text_outp function is called. The transparency attribute value returned by the function corresponds to the T bit in the TMS340 graphics processor's CONTROL register. The effect of transparency in conjunction with the pixel-processing operation and the plane mask is described in the user's guides for the TMS34010 and TMS34020. Example Use the get_transp function to verify that transparency is disabled by default. Use the text_out function to print the value returned by the get_transp function to the screen. #include 4-46 Core Functions Return Address at TMS340 Trap Vector get_vector Syntax #include */ Type Description Core The get_vector function returns one of the TMS340 graphics processor's trap vectors. This function provides a portable means of obtaining the entry point to a trap service routine, regardless of whether the actual trap vector is located in RAM or ROM. Argument trapnum specifies a trap number in the range from -32768 to 32767 for a TMS34020, and from 0 to 31 for a TMS34010. The value returned by the function is the 32-bit address contained in the designated trap vector. Example Use the get_vector function to retrieve whatever address happens to be in trap vector 0. Use the text_out function to print the value returned by the get_vector function to the screen as an 8-digit hexadecimal number. #include 4-47 get_videomode Syntax Return Current Video Mode #include Type Description Host-only The get_videomode function returns the current video mode. Possible video modes are discussed in the set_videomode function. This function is normally used to obtain the video mode before entering TIGA mode. Once the TIGA application has completed, the previous video mode can be easily restored. 4-48 Core Functions Return Window-Clipping Mode get_windowing Syntax #include Type Description Core The get_windowing function returns a 2-bit code designating the current window-checking mode. There are four windowing modes: 1) 2) 3) 002 012 102 Window clipping disabled Interrupt request on write to pixel inside window Interrupt request on write to pixel outside window Clip to window 4) 112 TIGA's graphics library drawing functions assume that the TMS340 graphics processor is configured in windowing mode 3. Changing the windowing mode from this default may result in undefined behavior if calls are made to the extended graphics library functions. The 2-bit code for the window-clipping mode corresponds to the W field in the TMS340 graphics processor's control register. The effects of the W field on window-clipping operations are described in the user's guides for the TMS34010 and TMS34020. Immediately following initialization of the drawing environment, the system is configured in windowing mode 3, which is the default. 4-49 get_wksp Syntax Return Workspace Information #include */ */ Type Description Core The get_wksp function retrieves the parameters that define the current offscreen workspace. None of the current TIGA core or extended functions use this workspace; it is provided to support future graphics extensions that require storage for edge flags or region-of-interest masks. Not all display configurations may have sufficient memory to support an offscreen workspace. Argument addr is the base address of the offscreen workspace. Argument pitch is the difference in memory addresses of two adjacent rows in the offscreen workspace. A nonzero value is returned by the function if a valid offscreen workspace is currently allocated. A value of 0 is returned if no offscreen workspace is allocated; in this case, the workspace address and pitch are not retrieved by the function. The offscreen workspace is a 1-bit-per-pixel bitmap of the same width and height as the screen. If the display hardware provides sufficient offscreen memory, the workspace can be allocated statically. By convention, the workspace pitch retrieved by the get_wksp function is nonzero when a workspace is allocated; the pitch can be checked following initialization to determine whether a workspace is statically allocated. The workspace can be allocated dynamically by calling the set_wksp function with the address of a valid workspace in memory and a nonzero pitch; it can be deallocated by calling set_wksp with a pitch of 0. 4-50 Core Functions Enable/Disable GM Idle Function Execution gm_idlefunction Syntax #include */ */ Type Description Core The gm_idlefunction function enables the function specified by the module number argument mn and by the function number argument fn to be called whenever the TIGA graphics manager (GM) is idle, that is, is not servicing a TIGA function call. The argument mn corresponds to the module identifier returned by the install_rlm function. The argument fn corresponds to the index of the desired function within the specified module. To ensure correct operation, the function specified to gm_idlefunction must conform to the following requirements to ensure correct operation: Be currently loaded into TMS340 memory (by calling the install_rlm function). The idle function, when called by the TIGA GM, is passed one 32-bit argument on the program stack (STK). This argument informs the idle function whether or not a TIGA function is next to be executed. Valid arguments are: 0 = No TIGA command is pending. 1 = A TIGA command is pending (this is the last time the idle function is called before servicing the TIGA function). The idle function must conform to the standard TMS340 C-calling conventions. Save and restore all registers that it uses (except for A8). Not modify the sign or sign extent of field 1. To disable the GM idle function calling feature, specify a module number of -1. If no function corresponding to the specified module and function numbers is currently loaded in TMS340 memory, 0 is returned. Otherwise, 1 is returned. 4-51 gsp2cop Syntax Copy From TMS340 Memory to Coprocessor Memory #include Type Description Core The gsp2cop function copies data from TMS340 space into the TMS34082 coprocessor space with ID copid (a number from 0 to 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. 4-52 Core Functions Transfer Data Within TMS340 Memory gsp2gsp Syntax #include */ */ Type Description Core The gsp2gsp function copies the specified number of bytes from one region of the TMS340 graphics processor's memory to another. Argument src is a pointer to the source array, and argument dst is a pointer to the destination array. Argument length is the number of contiguous 8-bit bytes to be transferred from the source to the destination. If the source and destination arrays overlap, the function adjusts the order in which the bytes are transferred so that no source byte is overwritten before it has been copied to the destination. Unlike the standard character string function strncpy, the gsp2gsp function does not restrict the alignment of the source and destination addresses to even-byte boundaries in memory. Arguments src and dst may point to any bit boundaries in memory. 4-53 gsp2host Syntax Move Data From TMS340 Memory to Host Memory #include */ */ */ */ Type Description Host-only The gsp2host function copies length number of bytes from TMS340 memory pointed to by gptr to host memory at hptr. 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). gptr is a pointer to TMS340 memory. It must be byte-aligned (that is, 3 LSBs must be 0). hptr is a pointer to host memory. It must be declared as a long pointer (for example, segment:offset format). All data being passed to the host must fit in the segment specified by hptr. No segment boundary checking is performed by this function. 4-54 Core Functions Copy Rectangular Memory Area From TMS340 to Host gsp2hostxy Syntax #include Type Description Host-only 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, sptch, is the difference in the linear addresses between two pixels in the same column and adjacent rows of the bitmap in TMS340 memory. dptch 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: The source pitch ( on the TMS340 side), sptch, though a long variable, must be a multiple of 16 and less than 16 bits long. The source address, saddr, must also be a multiple of 16. 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. 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. 4-55 gsp_calloc Syntax Clear and Allocate TMS340 Memory #include */ */ Type Description Core The gsp_calloc function allocates a packet of TMS340 memory large enough to contain nmemb objects of the specified size and returns a pointer. If it cannot allocate the packet (that is, if it runs out of 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. 4-56 Core Functions Execute a COFF Program gsp_execute Syntax #include Type Description Host-only 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 starting TMS340 address of the program. On most TMS340 boards, this address loads into the NMI vector, and an NMI is performed. Example #include 4-57 gsp_free Syntax Free TMS340 Memory From Allocation #include Type Description Core The gsp_free function deallocates 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 sucessfully frees a valid TMS340 pointer. 4-58 Core Functions Allocate TMS340 Memory gsp_malloc Syntax #include /* size (in bytes) of block */ Type Description Core The gsp_malloc function allocates a packet of TMS340 memory of a specified size and returns a pointer. 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_minit, and gsp_realloc. 4-59 gsp_maxheap Syntax Return Largest Free Block #include Type Description Core 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 an object; for example, a bitmap can be downloaded. 4-60 Core Functions Reinitialize Dynamic Memory Pool gsp_minit Syntax #include Type Description Core The gsp_minit function reinitializes and frees all unsecured memory blocks in the TMS340 dynamic memory heap pool. Any previously allocated blocks are no longer allocated, and all pointers to such blocks become invalid after this procedure is called. In previous versions of TIGA, this function could modify the size of the system stack by using argument stack_size. TIGA 2.0 no longer supports this feature; however, to maintain downward compatibility, you should still specify an argument of type long for this function. Be careful when you use this function: all unsecured allocated blocks of memory are freed, including the background save area for the cursor (if stored in heap). Disable the cursor before calling this function and install a new cursor via a call to set_curs_shape afterward. If the workspace set by the set_wksp function was previously allocated in heap, it will have to be reset before using it. The gsp_minit function 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. 4-61 gsp_realloc Syntax Reallocate TMS340 Memory #include */ */ Type Description Core 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 because 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. 4-62 Core Functions Allocate Memory Block gsph_alloc Syntax #include Type Description Core The gsph_alloc function allocates a memory block of the size (in bytes) specified by the argument size and returns a handle identifying this memory block. The handle is used in subsequent handle-based memory functions to specify the memory block. The memory block's type defaults to moveable and undeletable. The function gsp_memtype may be used to modify the memory block's characteristics. If insufficient memory is available, NULL (0) is returned. See also gsph_memtype. 4-63 gsph_calloc Syntax Allocate and Clear Memory #include Type Description Core The gsph_calloc function allocates an area of memory whose size is specified by the arguments ecount and esize. Argument ecount specifies the number of blocks to be allocated, and argument esize specifies the size, in bytes, of each block. The allocated memory is then cleared (set to zero). A handle to the allocated memory area is returned. If an error occurs, NULL (0) is returned. 4-64 Core Functions Invoke Memory Compaction Routine gsph_compact Syntax #include Type Description Core The gsph_compact function invokes TIGA's memory manager compaction routine. This routine attempts to reorganize allocated memory blocks to create larger, contiguous memory areas for further allocation. The argument purge specifies if memory blocks marked as deletable are to be purged during compaction. If purge is set to true (1), then deletable blocks are purged. See also gsph_memtype. 4-65 gsph_deref Syntax Return Pointer to Memory Block Referenced by Handle #include Type Description Core The gsph_deref function returns a void pointer to the memory block (in TMS340 processor memory) referenced by the argument handle. This is useful if an application requires direct access to the memory block address. The argument handle must be a valid handle returned by either the gsph_alloc or gsph_falloc functions. If the handle passed is invalid, NULL (0) is returned by this function. See also gsph_alloc and gsph_falloc. 4-66 Core Functions Allocate Memory Block With Associated Function gsph_falloc Syntax #include Type Description Core The gsph_falloc function allocates a memory block of the size (in bytes) specified by argument size and returns a handle identifying this memory block. The handle is used in subsequent handle-based memory functions to specify the memory block. The argument func is a pointer to a TMS340-resident function of type void, which is called if this memory block is ever moved or deleted by TIGA's memory manager. Note that the memory block's flags must be set accordingly to enable this function to be called. The argument flags defines the memory block's initial characteristics. flags is composed of the following manifest constants: BLK_FUNCDELETE Call specified function when block is deleted BLK_FUNCMOVE Call specified function when block is moved The memory block's type defaults to moveable and undeletable. However, if the BLK_FUNCDELETE flag is specified, then the block is marked as deletable. The function gsph_memtype may also be used to modify the memory block's characteristics. If insufficient memory is available, NULL is returned. See also gsph_memtype. 4-67 gsph_fcalloc Syntax Allocate and Clear Memory With Associated Function #include Type Description Core The gsph_fcalloc function allocates an area of memory whose size is specified by arguments ecount and esize. Argument ecount specifies the number of blocks to be allocated, and argument esize specifies the size, in bytes, of each block. The allocated memory is then cleared (set to zero). A handle to the allocated memory area is returned. If an error occurs, NULL (0) is returned. The argument func is a pointer to a TMS340-resident function of type void, which is called if this memory block is ever moved or deleted by TIGA's memory manager. Note that the memory block's flags must be set accordingly to allow this function to be called. The argument flags defines the memory block's initial characteristics. It is composed of the following manifest constants: BLK_FUNCDELETE Call specified function when block is deleted BLK_FUNCMOVE Call specified function when block is moved The memory block's type defaults to moveable and undeletable. However, if the BLK_FUNCDELETE flag is specified, then the block is marked as deletable. The function gsph_memtype may also be used to modify the memory block's characteristics. 4-68 Core Functions Return Handle to Specified Memory Address gsph_findhandle Syntax #include Type Description Core The gsph_findhandle function returns the handle of the memory block specified by the TMS340 memory address in argument memptr. If the argument does not point to a valid memory block, the function returns NULL (0).This function performs the inverse of the gsph_deref function. See also gsph_deref. 4-69 gsph_findmem Syntax Return Information About Specified Memory Address #include Type Description Core The gsph_findmem function returns information about the memory block containing the TMS340 address specified by the argument memptr. This function returns, in argument handle, the handle of the memory block specified by the memory address in argument memptr; whereas the gsph_deref function returns a pointer to the memory block pointed to by the handle. The value of handle is NULL (0) if the memory address is not part of an allocated block. Argument flags contains information about the memory block's status. Valid flags include: BLK_INUSE BLK_DELETABLE BLK_LOCKED This memory block is currently in use. This memory block may be deletable. This memory block must remain at its current address. It may not be moved during compaction by TIGA's memory manager. Secured system memory block (will not be purged by a gsp_minit() or gsph_init() function call). When the block is moved by TIGA's memory manager, a call is made to the previously installed memory function. BLK_SECURED BLK_FUNCMOVE BLK_FUNCDELETE When the block is purged by TIGA's memory manager, a call is made to the previously installed memory function. The function returns 0 1 -1 if the memory address supplied marks the start of a memory block managed by the memory manager. if the memory address is contained in a memory block managed by the memory manager. if the memory lies outside that managed by the memory manager. See also gsph_deref and gsph_memtype. 4-70 Core Functions Free Block of Memory gsph_free Syntax #include Type Description Core The gsph_free function frees the memory associated with the memory block specified by the argument handle. This memory block is returned to the memory pool and is then available for further allocation. The argument handle must be a valid handle returned by either the gsph_alloc or gsph_falloc functions. No value is returned by this function. See also gsph_alloc and gsph_falloc. 4-71 gsph_init Syntax Initialize All User Memory and Compact All Segments #include Type Description Core The gsph_init function frees all allocated nonsecured memory blocks and performs a compaction on this freed memory. 4-72 Core Functions Return Size of Largest Block Without Compaction gsph_maxheap Syntax #include Type Description Core The gsph_maxheap function returns the size, in bytes, of the largest memory block that can be allocated with the gsph_alloc or gsph_falloc functions. Note that the size returned by this function assumes that the memory block will be allocated from the current memory state. In other words, it is functionally equivalent to the gsp_maxheap function. This function is similar to the gsph_totalfree function, with the exception of the memory state assumption. See also gsph_alloc, gsph_falloc, and gsph_totalfree. 4-73 gsph_memtype Syntax Set Characteristics of Memory Block #include Type Description Core The gsph_memtype function allows the characteristics of the memory block identified by the argument handle to be modified. The argument handle must be a valid handle returned by either the gsph_alloc or gsph_falloc functions. The argument flags specifies the new characteristics of the specified memory block and is composed of the following manifest constants, which are defined in tiga.h: BLK_DELETABLE BLK_LOCKED This memory block may be deleted. This memory block must remain at its current address. It may not be moved during compaction by TIGA's memory manager. Secured system memory block (will never be moved or purged by compaction or by a call to gsph_init or gsp_minit). When the block is moved by TIGA's memory manager, a call will be made to the previously installed memory function. BLK_SECURED BLK_FUNCMOVE BLK_FUNCDELETE When the block is purged by TIGA's memory manager, a call will be made to the previously installed memory function. See also gsph_alloc, gsph_falloc, and gsph_maxheap. 4-74 Core Functions Reallocate Block of Memory gsph_realloc Syntax #include Type Description Core The gsph_realloc function allows the size of a previously allocated memory block to be modified. The argument handle specifies the memory block whose size is to be adjusted. The argument handle must be a valid handle returned by either the gsph_alloc or gsph_falloc functions. The argument size specifies the new size of the memory block in bytes. The new size of the memory block (in bytes) is returned. If the requested size could not be allocated, then the amount that was actually allocated is returned. See also gsph_alloc and gsph_falloc. 4-75 gsph_totalfree Syntax Return Size of Largest Block Without Compaction #include Type Description Core The gsph_totalfree function returns the size, in bytes, of the largest contiguous memory block potentially available after compaction. Note that you will have to call the function gsph_compact before allocating a memory block of the size returned by the gsph_totalfree function. 4-76 Core Functions Move Data From Host Memory to TMS340 Memory host2gsp Syntax #include */ */ */ */ Type Description Host-only The host2gsp function copies length number of bytes from the host memory pointed to by hptr, 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). Argument hptr is a pointer to host memory and must be declared as a long pointer (that is, segment:offset format). Argument gptr is a pointer to TMS340 memory. It must be byte-aligned (that is, 3 LSBs must be 0). All data being passed from the host must fit in the segment specified by hptr. No segment-boundary checking is performed by this function. Example See get_offscreen_memory. 4-77 host2gspxy Syntax Copy Rectangular Memory Area From Host to TMS340 #include Type Description Host-only 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, sptch, 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 dptch is the same for TMS340 memory. Note that dptch and daddr must be multiples of 16. 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). 4-78 Core Functions Initialize Palette init_palet Syntax #include Type Description Core The init_palet function initializes the first 16 entries of the palette to the EGA default colors: Index 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Color black blue green cyan red magenta brown light gray dark gray light blue light green light cyan light red light magenta yellow white If the palette contains more than 16 entries, the function replicates the 16 colors through the remainder of the palette. At 2 bits per pixel, palette indices 0-3 are assigned the default colors black, green, red, and white. At 1 bit per pixel, palette indices 0 and 1 are assigned the default colors black and white. If the palette is nonprogrammable, the function has no effect. The palette is also initialized to the default colors any time the drawing environment is initialized. Initialization occurs when the set_videomode function is called with the style argument specified as INIT or INIT_GLOBALS, or when set_config is called with the init_draw argument set to true. Example Use the init_palet function to restore the default colors. #include */ */ 4-79 init_text Syntax Initialize Text-Drawing Environment #include Type Description Core The init_text function removes all installed fonts from the font table and selects the system font (font 0) for use in subsequent text operations. It also resets all text drawing attributes to their default states. The set_videomode and set_config functions also initialize the font table and text attributes as part of their initialization of the drawing environment. Example Use the init_text function to discard all installed fonts from the font table and select the default font. The install_font and select_font functions from the TIGA graphics library are used to install and select a proportionally spaced font. Note that the function loadinst_font is called to load and install a TIGA font from a font file. The loadinst_font is not a TIGA function but does make calls to various TIGA functions to load a font. Refer to the install_font function description in Chapter 5 for a complete source listing of the loadinst_font function. #include */ */ 4-80 Core Functions Install Absolute Load Module install_alm Syntax #include /* load module filename */ Type Description Host-only The install_alm function installs an absolute load module (ALM). ALMs were required before version 2.0 of TIGA because the downloading of a user extension to TIGA was done by calling the linking loader. This is not the case in versions 2.0 and higher; so ALMs are now redundant. This function is included purely to maintain compatibility with TIGA drivers written before version 2.0 of TIGA.The install_alm function installs the absolute load module (specified by argument alm_name) into theTIGA graphics manager 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 TIGA, and the priority information associated with each can be retrieved, once installation is complete, with a call to get_isr_priorities, 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 8. 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 function number and command type using the bitwise-OR operator ( | ). The function returns these error codes: Error Code -3 Description Memory Error - Either there is not enough TMS340 memory to load the ALM, or the address at which the ALM was linked to when it was created does not match the address at install time. Check this by trying to install the ALM by invoking TIGALNK from the command line with the la option. Error Accessing ALM - Unable to open ALM for reading, or the contents of the file were in unexpected format. The spelling of the ALM filename does not match the ALM filename in the current directory, or the -l option of the TIGA environment variable is not set up correctly, or alternatively, the file has been corrupted, in which case it will need to be recreated. -8 Example See subsection 8.3.2 on page 8-7. 4-81 install_primitives Syntax Install Graphics Library Functions #include Type Description Host-only The install_primitives function is similar to a call to install_rlm and is used to download the TIGA extended graphics library functions such as draw_line etc. These functions must be loaded before an application can call them. If the extended graphics library functions are currently installed when install_primitives is called, no action is performed. The function returns the module id of the installed graphics library functions if successful. If an error occurred, a negative error code is returned as follows: Error Code -3 -6 Description Out of Memory -- Not enough TMS340 memory to load the extended graphics library functions. Error Accessing RLM -- Unable to open extended functions (primitives) RLM for reading. Either the file extprims.rlm is missing from the main TIGA directory, or the -m option of the TIGA environment variable is not set up correctly. Symbol Reference -- An unresolved symbol was referenced by the extended graphics library. To determine the name of the symbol, invoke TIGALNK from the command line by using the -ec option. Error Loading COFF File -- An error was obtained in the loading of the extprims.rlm COFF file. Recopy the extprims.rlm file from the installation disk. Out of Symbol Memory -- Not enough TMS340 memory to store the symbols of the extended graphics library. -10 -14 -15 Example #include Core Functions Install Relocatable Load Module install_rlm Syntax #include */ Type Description Host-only The install_rlm function installs the relocatable load module (specified by the argument 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 get_isr_priorities, which returns a priority list for the last block of ISRs installed. If an error occurs, a negative value is returned. Otherwise, a module identifier is returned. Whenever a routine contained within this module is specified, join the module identifier with the routine number and command type by using the bitwise-OR operator ( | ). The rlm_name argument can contain the special flag %f appended to the end of the name (for example, install_rlm("myrlm %f")). This flag flushes the symbols so that they are not loaded into TMS340 memory. If this flag is absent, the global symbols in the RLM are stored in TMS340 memory so that subsequently installed RLMs can reference these symbols. If this is not required -- that is, if there are no RLMs to be installed that reference symbols in this RLM,-- then using the %f flag enables the TMS340 memory to be used by the application's heap pool. For more details on extensibility and the use of this function, see Chapter 8. The function returns these error codes: Error Code -3 -6 Description Out of Memory -- Not enough TMS340 memory to load the RLM. Error Accessing RLM -- Unable to open RLM for reading. Either the spelling of the RLM filename does not match the RLM filename in the current directory, or the -l option of the TIGA environment variable is not set up correctly. Symbol Reference -- An unresolved symbol was referenced by the RLM. Determine the name of the symbol, either by producing a link map for the RLM or by invoking TIGALNK from the command line using the -ec flag. Description (continued) Error Loading RLM COFF File -- An error was obtained in the load of the RLM COFF file. Recreate the RLM and try again. -10 Error Code -14 4-83 install_rlm Install Relocatable Load Module -15 Example Out of Symbol Memory -- Not enough TMS340 memory to store the symbols of the RLM. See subsection 8.3.1 on page 8-6. 4-84 Core Functions Install User Error Handler install_usererror Syntax #include Type Description Host-only The install_usererror function installs a host-resident user error function that is called when an error is encountered in the host communications. The default user error function simply prints a message to the screen when an error occurs. You 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; These error codes are passed to the error function: 1 2 3 Timeout with TMS340 communication on trying to load new function; that is, a previous function has not completed. Timeout on waiting for TMS340 function to complete; that is, the function just invoked has not completed. Parameter allocation failure; not enough memory to allocate a buffer to download data from the current function. The return value from the installed handler tells TIGA whether to keep trying to determine if the TMS340 processor has completed (if nonzero) or to abort (if zero). Example #include 4-85 install_usererror Install User Error Handler main() { short i, x, y; CONFIG config; init_tiga(1); get_config(&config); install_usererror(usererror); /* initialize nofpts points to some value x = y = 0; for (i = 0; i < nofpts*2; ) { lotofpts[i++] = x; lotofpts[i++] = y; if (i % 4) { 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(1000); set_pensize(64,64); /* tie up the TMS340 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 TMS340 pen_polyline_a(nofpts, lotofpts); /* wait for TMS340 side to finish (to produce timeouts) synchronize(); term_tiga(); } */ */ */ */ */ */ */ 4-86 Core Functions Return Leftmost One Bit Number lmo Syntax #include /* 32-bit integer */ Type Description Core The lmo function calculates the bit number of the leftmost 1 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 of 0 to 31. If the argument is 0, a value of -1 is returned. Example Use the lmo function to return the bit number of the leftmost 1 in the integer value 1234. #include 4-87 loadcoff Syntax Load COFF FIle #include Type Description Host-only 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 by argument filename. It returns false (0) 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 COFF file. See gsp_execute. Example 4-88 Core Functions Return Status of Page Flipping page_busy Syntax #include Type Description Core The page_busy function returns a nonzero value as long as a previously requested video page flip has not yet occurred. This function is used in conjunction with the page_flip function to achieve flickerless, double-buffered animation. Before the page_busy function is called, the page_flip function is called to request the page flip, which is scheduled to occur when the bottom line of the screen has been scanned on the monitor. The page_flip function returns immediately without waiting for the requested page flip to be completed, and the page_busy function is used thereafter to monitor the status of the request. Between the call to the page_flip function and the time the page flip actually occurs, the page_busy function returns a nonzero value. After the page flip has occurred, the page_busy returns a value of 0 (until the next time page_flip is called). Double buffering is a technique used to achieve flickerless animation in graphics modes supporting more than one video page. The TMS340 graphics processor alternately draws to one page (or frame buffer) while the other page is displayed on the monitor. When the processor has finished drawing, the new page is ready to be displayed on the screen in place of the old page. The actual flipping (or switching) of display pages is delayed until the vertical blanking interval, however, to avoid causing the image on the screen to flicker. The rationale for providing separate page_flip and page_busy functions is to make the time between a page flip request and the actual completion of the page flip available to the application program for performing background calculations. For example, the main loop of a 3-D animation program can be structured as follows: for (disp = 1, draw = 0; ; disp ^= 1, draw ^= 1) { page_flip(disp, draw); < Perform 3D background calculations. > while (page_busy()) ; < Draw updated 3D scene. > } If the page_flip function is used alone without the page_busy function, you risk drawing to a page that is still being displayed on the screen. Example Use the page_busy function to smoothly animate an object rotating in a circle. The best effect is achieved in a graphics mode that provides double buffering (more than one video page). If the mode supports only a single page, the program will still run correctly, but the display may flicker. 4-89 page_busy Return Status of Page Flipping #include /* radius of circle of rotation /* angular increment = 1>>N radians */ */ main() { short disp = 0, draw = 1; long x, y; init_tiga(0); x = (long)RADIUS << 16; y = 0; do { page_flip(disp, draw); x -= y >> N; y += x >> N; while (page_busy()) ; clear_page(-1); text_out((x>>16)+RADIUS, (y>>16)+RADIUS, "*"); disp ^= 1; draw ^= 1; }while(!kbhit()); getch(); term_tiga(); } 4-90 Core Functions Flip Display and Drawing Pages page_flip Syntax #include */ Type Description Core The page_flip function is used to switch between alternate video pages. This function is used in conjunction with the page_busy function to achieve flickerless, double-buffered animation. Argument disp is a nonnegative value indicating the number of the video page to be displayed--that is, output to the monitor screen. Argument draw is a nonnegative value indicating the number of the video page to be drawn to; this page is the target of all graphics output directed to the screen. All graphics modes support at least one video page, page number 0. In graphics modes supporting more than one page, the pages are numbered 0, 1, and so on. Valid values for arguments disp and draw are restricted to video page numbers supported by the current graphics mode. If either argument is invalid, the function behaves as if both arguments are 0; that is, page 0 is selected as both the display page and the drawing page. This behavior permits programs written for double-buffered modes to be run in single-buffered modes. Although the single-buffered display may flicker, the program will execute at nearly the same frame rate as in the double-buffered mode. The number of pages in a particular graphics mode is specified in the num_pages field of the CONFIG structure returned by the get_config function. If the num_pages field contains some value N, the N pages are numbered 0 through N-1. The page_flip function requests that a page flip be performed but returns immediately without waiting for the requested page flip to be completed. Upon return from the function, all subsequent screen drawing operations are directed toward the page specified by argument draw. The monitor display, however, is not updated to the page specified by argument disp until the start of the next vertical blanking interval (which occurs when the monitor finishes scanning the last line on the screen). Between the call to the page_flip function and the time the page flip actually occurs, the page_busy function returns a nonzero value. This is true, regardless of whether the disp and draw arguments are the same or whether the new display page is the same as the old display page. After the page flip has occurred, the page_busy returns a value of 0 (until the next time page_flip is called). 4-91 page_flip Flip Display and Drawing Pages Double buffering is a technique used to achieve flickerless animation in graphics modes supporting more than one video page. The TMS340 graphics processor alternately draws to one page (or frame buffer) while the other page is displayed on the monitor. When the processor has finished drawing, the new page is ready to be displayed on the screen in place of the old page. The actual flipping (or switching) of display pages is delayed until the vertical blanking interval, however, to avoid causing the image on the screen to flicker. Example Use the page_flip function to smoothly animate two moving rectangles. Use the fill_rect function from the extended functions library to draw the rectangles. The selected graphics mode is assumed to be double-buffered--that is, to support more than one video page. If the mode supports only a single page, the program will still run correctly, but the display may flicker. #include /* radius of circle of rotation /* pixel processing operation code /* angular increment = 1>>N radians */ */ */ main() { short disp = 0, draw = 1; long x, y; init_tiga(1); set_ppop(XOR); x = (long)RADIUS << 16; y = 0; do { page_flip(disp, draw); x - = y >> N; y += x >> N; while (page_busy()) ; clear_screen(-1); fill_rect(2*RADIUS, RADIUS/4, 10, RADIUS+(y>>16)); fill_rect(RADIUS/4, 2*RADIUS, RADIUS+(x>>16), 10); disp ^= 1; draw ^= 1; }while(!kbhit()); getch(); term_tiga(); } 4-92 Core Functions Read From B-File Register peek_breg Syntax #include */ Type Description Core The peek_breg function returns the contents of a TMS340 B-file register. Argument breg is a number in the range of 0 to 15 that designates a register in the TMS340 graphics processor's B file. Argument values 0 through 14 correspond to registers B0 through B14. An argument value of 15 designates the SP (system stack pointer). The function ignores all but the 4 LSBs of argument breg. The return value is 32 bits. Use the peek_breg function to read the contents of register B9, also referred to as the COLOR1 register. Register B9 contains the foreground color in pixel-replicated form. For example, at 4 bits per pixel, a foreground pixel value of 7 is replicated 8 times to form the 32-bit value 0x77777777. #include Example 4-93 poke_breg Syntax Write to B-File Register #include */ */ Type Description Core The poke_breg function loads a 32-bit value into a B-file register. Argument breg is a number in the range of 0 to 15 that designates a register in the TMS340 graphics processor's B file. Argument values 0 through 14 correspond to registers B0 through B14. An argument value of 15 designates the SP (system stack pointer). The function ignores all but the 4 LSBs of argument breg. Argument val is a 32-bit value that is loaded into the designated register. Use the poke_breg function to load the value 0 into the TMS340 graphics processor's register B6, also referred to as the WEND register. Use the fill_rect function from the TIGA graphics library to draw a filled rectangle that is specified to be larger than the clipping window. Register B6 contains the upper x and y limits for the clipping window. Following the poke_breg call, the clipping window contains only the single pixel at (0, 0). Obviously, the set_clip_rect function provides a safer and more portable means to adjust the clipping window than the one used in this example. #include Example 4-94 Core Functions Return Rightmost One Bit Number rmo Syntax #include /* 32-bit integer */ Type Description Core The rmo function calculates the bit number of the rightmost 1 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 Use the rmo function to calculate the bit number of the rightmost 1 for each integer in the range 1 to 127. Represent the result graphically as a series of 127 adjacent vertical lines. Use the fill_rect function from the TIGA graphics library to draw the vertical lines. #include 4-95 set_bcolor Set Background Color Syntax #include /* background pixel value */ Type Description Core The set_bcolor function sets the background color for subsequent drawing operations. Argument color specifies the pixel value to be used to draw background pixels. Given a pixel size of N bits, the pixel value is contained in the N LSBs of the argument; the higher order bits are ignored. The function creates a 32-bit replicated pixel value and loads the result into the TMS340 graphics processor's register B8, also referred to as the COLOR0 register. For example, given a pixel size of 4 bits and a pixel value of 6, the replicated pixel value is 0x66666666. Example Use the set_bcolor function to swap the foreground and background colors. #include 4-96 Core Functions Set Clipping Rectangle set_clip_rect Syntax #include */ */ Type Description Core The set_clip_rect function specifies the position and size of the rectangular clipping window for subsequent drawing operations. Arguments w and h specify the width and height of the clipping window in pixels. Arguments xleft and ytop specify the x and y coordinates at the top-left corner of the window, relative to the drawing origin in effect at the time set_clip_rect is called. If the specified clipping window extends beyond the screen boundaries, the effective window is limited by the function to that portion of the specified window that actually lies on the screen. A call to the set_draw_origin function (in the TIGA graphics library) has no effect on the position of the clipping window until the set_clip_rect function is called. During initialization of the drawing environment, the clipping window is set to its default limits, which is the entire screen. The function updates the contents of the TMS340 graphics processor's registers B5 and B6, which are also referred to as the WSTART (window start) and WEND (window end) registers. These registers are described in the user's guides for the TMS34010 and TMS34020. Example Use the set_clip_rect function to specify a clipping window of width 192 pixels and height 128 pixels. Use the draw_line function to draw a series of concentric rays that emanate from a point within the window, but that extend beyond the window. The rays are automatically clipped to the limits of the window. Note that the call to set_clip_rect follows the call to the set_draw_origin function, and that the x-y coordinates (-80, -80) passed as arguments to set_clip_rect are specified relative to the drawing origin at (88, 88). 4-97 set_clip_rect Set Clipping Rectangle #include 4-98 Core Functions Set Foreground and Background Colors set_colors Syntax #include */ */ Type Description Core The set_colors function specifies the foreground and background colors to be used in subsequent drawing operations. Arguments fcolor and bcolor contain the pixel values used to draw the foreground and background colors, respectively. Given a pixel size of N bits, the pixel value is contained in the N LSBs of each argument; the higher order bits are ignored. The function creates 32-bit replicated pixel values and loads the results into the TMS340 graphics processor's registers B8 and B9, also referred to as the COLOR0 and COLOR1 registers. For example, given a pixel size of 4 bits and a pixel value of 3, the replicated pixel value is 0x33333333. Example Use the set_colors function to swap the default foreground and background colors. Use the text_out function to print a string of text with the colors swapped. #include 4-99 set_config Set Hardware Configuration Syntax #include */ */ Type Description Host-only The set_config function configures the display system in the specified graphics mode. Both the display hardware and graphics software environment are initialized. Note that calling the set_videomode function, with the mode argument set to TIGA and the style argument set to INIT or INIT_GLOBALS, performs identical initialization for the default graphics mode as described here. Argument graphics_mode specifies the graphics mode. All display systems provide at least one graphics mode, mode 0. In display systems supporting multiple modes, the modes are numbered 0, 1, and so on. Argument init_draw specifies whether the function initializes the drawing environment to its default state. If init_draw is nonzero, the environment is initialized; otherwise, the drawing environment remains unaltered. The set_config function returns a 16-bit value, encoded as follows: Bit 0: Bit 1: Bits 2-15: Status GM reloaded 0 (0=Error, 1=OK) (0=No, 1=Yes) If an invalid graphics_mode argument is specified, zero is returned. Otherwise, bit 0 is set to 1. Changing the graphics mode may change the memory map of the TMS340 side of TIGA. If this memory map change results in the alteration of the graphics manager (GM) load address, then set_config automatically reloads the GM and sets bit 1 of the return value to 1. If no reload is necessary, bit 1 is set to 0. Note that if the GM is reloaded, all downloaded extensions are flushed and allocated memory is freed. Therefore, it is recommended that an application use the set_config function before loading any TIGA extensions or allocating any TMS340 memory. The number of modes available for a particular hardware configuration is specified in the num_modes field of the CONFIG structure returned by the get_config function. The modes are numbered 0 through num_modes - 1. Following a call to set_config, the display system remains in the specified graphics mode until a subsequent call to set_config is made. Associated with each mode is a particular display resolution, pixel size, and so on. 4-100 Core Functions Set Hardware Configuration set_config The set_config function configures the following system parameters: horizontal and vertical video timing video-RAM screen-refresh cycles screen pixel size in bits screen dimensions (width and height in pixels) location in memory of one or more video pages (or frame buffers) default clipping window (entire screen) default color palette (See description of init_palet function.) default display and drawing pages (page 0 for both) default offscreen workspace (which may be null) If a nonzero value is specified for argument init_draw, the parameters of the drawing environment are initialized as follows: Pixel transparency is disabled. The pixel-processing operation code is set to its default value of 0 (the code for the replace operation). The plane mask is set to its default value of 0, which enables all bit planes. The foreground color is set to light gray and the background color to black. The screen is designated as both the source bit map and destination bit map. The drawing origin is set to screen coordinates (0, 0), which correspond to the pixel at the top left corner of the screen. The pen width and height are both set to 1. The current area-fill pattern is set to its default state, which is to fill with solid foreground color. The current line-style pattern is set to its default value, which is all 1s. All installed fonts are removed, and font 0, the permanently installed system font, is selected. The text x-y position coordinates are set to (0, 0). The text attributes are set to their initial states: alignment = 0 (top left) additional intercharacter spacing = 0 intercharacter gaps = 0 (leave gaps) The default graphics cursor, an arrow, is installed and selected. Example Use the set_config function to sequence the display through all available graphics modes. Use the draw_rect function to draw a box around the visible screen area, and use the text_out function to print the mode number and screen width and height to the screen. Use the wait_scan function to insert a delay of 120 frames between mode switches. 4-101 set_config Set Hardware Configuration #include /*delay in frames between modes */ init_tiga(1); for (mode = 0; set_config(mode, !0); mode++) { clear_screen(-1); get_config(&cfg); w = cfg.mode.disp_hres; h = cfg.mode.disp_vres; draw_rect(w-1, h-1, 0, 0); sprintf(s, "Graphics mode %d: %d-by-%d", mode, w, h); text_out(10, 10, s); for (i = NFRAMES; i; i- -) /* delay loop wait_scan(h); } term_tiga(); } */ 4-102 Core Functions Set Current Cursor Shape set_curs_shape Syntax #include Type Description Core The set_curs_shape function selects a new cursor shape. Argument shape is a pointer to the CURSOR structure in TMS340 memory of the desired cursor. Before this function is called, both the cursor shape and mask 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 the structure is loaded. 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 set_curs_shape with a shape argument of 0. If the cursor is disabled when a call to set_curs_shape is made, the new cursor shape is not loaded immediately. Instead, the new cursor shape is loaded on the next call to set_curs_state(1). For this reason, it is extremely important that the cursor shape and structure data resident in TMS340 memory not be freed or moved while the new cursor is being used. On the other hand, if the cursor is enabled when set_curs_shape is called, the cursor shape is loaded immediately, and the new cursor shape and structure data may be removed safely from TMS340 memory (assuming this cursor shape will never need to be selected again by the application). In the set_curs_xy function, (x, y) is the position of the top-left pixel of the cursor if hot_x and hot_y are zero. These values are subtracted from the current cursor position to give the top-left hand corner of the cursor's starting drawing point. For example, in a simple crosshairs cursor of width16 pixels and height 12 pixels, the hot_x is 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 crosshair cursor 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. 4-103 set_curs_shape Set Current Cursor Shape 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 and shape data, the background color is always 0. The foreground color of the shape and mask are specified by the color and mask_color fields, respectively, of the CURSOR structure. An example of cursor data follows. The mask data consists of an array width by height with 0s where the cursor is located and 1s elsewhere. The raster op for this data is AND(1), no transparency. The shape data is an array width by height with 1s where the cursor is located and 0s elsewhere. The raster op for the shape data is OR(8), no transparency. 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 Example masks for a simple crosshair 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 #include { 0xFF,0x87,0x03,0x00,0xFF,0x03,0x03,0x00,0xFF,0x03,0x02,0x00,0xFF,0x01,0x02,0x00, 0xFF,0x01,0x03,0x00,0xFF,0x00,0x03,0x00,0xFF,0x80,0x03,0x00,0x7F,0x80,0x03,0x00, 0x7F,0xC0,0x03,0x00,0x3F,0xC0,0x03,0x00,0x3F,0xE0,0x03,0x00,0x1F,0xE0,0x03,0x00, 0x1F,0xF0,0x03,0x00,0x0F,0xF0,0x03,0x00,0x0F,0xF8,0x03,0x00,0x07,0xF8,0x03,0x00, 4-104 Core Functions Set Current Cursor Shape set_curs_shape 0x07,0xFC,0x03,0x00,0x03,0xFC,0x03,0x00,0x03,0xFE,0x03,0x00,0x01,0xFE,0x03,0x00, 0x01,0xFF,0x03,0x00,0x00,0xFF,0x03,0x00,0x80,0xFF,0x03,0x00,0xC0,0xFF,0x03,0x00, 0xE0,0xFF,0x03,0x00,0xF0,0xFF,0x03,0x00,0xF8,0xFF,0x03,0x00,0xFD,0xFF,0x03,0x00, 0x00,0x00,0x00,0x00,0x00,0x78,0x00,0x00,0x00,0xF8,0x00,0x00,0x00,0xFC,0x00,0x00, 0x00,0x7C,0x00,0x00,0x00,0x72,0x00,0x00,0x00,0x26,0x00,0x00,0x00,0x39,0x00,0x00, 0x00,0x11,0x00,0x00,0x80,0x10,0x00,0x00,0x80,0x08,0x00,0x00,0x40,0x08,0x00,0x00, 0x40,0x04,0x00,0x00,0x20,0x04,0x00,0x00,0x20,0x02,0x00,0x00,0x10,0x02,0x00,0x00, 0x10,0x01,0x00,0x00,0x08,0x01,0x00,0x00,0x88,0x00,0x00,0x00,0x84,0x00,0x00,0x00, 0x44,0x00,0x00,0x00,0x4E,0x00,0x00,0x00,0x3E,0x00,0x00,0x00,0x1E,0x00,0x00,0x00, 0x0E,0x00,0x00,0x00,0x06,0x00,0x00,0x00,0x02,0x00,0x00,0x00,0x00,0x00,0x00,0x00 }; /* Pencil cursor structure CURSOR far pencil = { 0x0000, 0x001B, 0x0011, 0x001C, 0x0020, 0x0FL, 1, 8, 0x0FFFFFFFFL, 0x0L */ }; /* Shape for Arrow2 cursor unsigned short far Arrow2Data[] = { 0x0010, 0x0018, 0x001C, 0xFFFE, 0xFFFF, 0xFFFE, 0x001C, 0x0018, 0x0010, 0x0000, 0x0000, 0x0008, 0x000C, 0x7FFE, 0x000C, 0x0008, 0x0000, 0x0000 */ }; /* Arrow2 cursor structure CURSOR far Arrow2 = { 00x0000, 0x0004, 0x0010, 0x0009, 0x0010, 0x0FL, 0x0020, 0x0020, 0x0FFFFFFFFL, 0x0L */ }; struct { short x,y; /* coordinates short left, right; /* buttons short x1,y1, x2,y2; /* boundary }mouse; union REGS regs; /* this function checks if a mouse driver is installed check_mouse() { regs.x.ax = 0; int86(0x33,®s,®s); return(regs.x.ax); } mouse_driver() { /* get mouse coordinates regs.x.ax = 11; int86(0x33,®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; */ */ */ */ */ */ 4-105 set_curs_shape Set Current Cursor Shape if (mouse.y > mouse.y2) mouse.y = mouse.y2; /* Tell the TMS340 cursor set_curs_xy(mouse.x, mouse.y); /* get the mouse buttons regs.x.ax = 3; int86(0x33,®s,®s); mouse.left = regs.h.bl & 1; mouse.right = (regs.h.bl & 2) >> 1; } void install_cursor(type) short type; /* 0=default(arrow), 1=user(pencil), 2=Arrow2 { static PTR gpUserCurs1 = 0L; /* Address of user cursor1 in TMS340 mem static PTR gpUserCurs2 = 0L; /* Address of user cursor2 in TMS340 mem CURSOR *hpCursStruct; void *hpCursData; PTR *gpCursStruct; switch(type) { case 1: /* Pencil cursor hpCursStruct = &pencil; hpCursData = (void *)PencilData; gpCursStruct = (PTR *)&gpUserCurs1; break; case 2: /* Arrow2 cursor hpCursStruct = &Arrow2; hpCursData = (void *)Arrow2Data; gpCursStruct = (PTR *)&gpUserCurs2; break; default: set_curs_shape((PTR)0);/* Default cursor return; } if(*gpCursStruct == 0L) { unsigned short num_bytes; /* download cursor shape data to TMS340 */ num_bytes = ((hpCursStruct->height * hpCursStruct->pitch) << 1) >> 3; hpCursStruct->data = (PTR)gsp_malloc(num_bytes); host2gsp(hpCursData, hpCursStruct->data, num_bytes, 0); /* download cursor structure to TMS340 num_bytes = sizeof(CURSOR); *gpCursStruct = (PTR)gsp_malloc(num_bytes); host2gsp(hpCursStruct, *gpCursStruct, num_bytes, 0); } set_curs_shape( *gpCursStruct ); } main() { char key; 4-106 */ */ */ */ */ */ */ */ */ Core Functions Set Current Cursor Shape set_curs_shape short CursorType = 1, fgc = 0; if(!check_mouse()) { printf("Mouse driver needs to be installed to run this example\n"); exit(0); } init_tiga(1); printf("Press...\n"); printf(" ESC to quit\n"); printf(" SPACE to toggle cursor shapes\n"); printf(" LEFT mouse button to draw points\n"); printf(" C to change cursor color\n"); /* assign a new cursor shape install_cursor(CursorType); /* initialize mouse to the center of the screen get_config(&config); mouse.x = config.mode.disp_hres>>1; mouse.y = config.mode.disp_vres>>1; 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(1); for(;;) { /* move the cursor with the mouse mouse_driver(); /* if left button pressed draw a point if (mouse.left) draw_point(mouse.x, mouse.y); if(kbhit()) switch(getch()) { case ' ' : if(++CursorType > 2) CursorType = 0; install_cursor(CursorType); break; case 'c' : case 'C' : if(++fgc == config.mode.palet_size) fgc = 1; if(CursorType==2) set_cursattr(fgc,0x0FFFFFFFFL,0x0020,0x0020); else set_cursattr(fgc,0x0FFFFFFFFL,8,1); break; case ESC : set_curs_state(0);/* Turn cursor off term_tiga(); } } } */ */ */ */ */ */ */ 4-107 set_curs_state Set Current Cursor State Syntax #include Type Description Example Core The set_curs_state function enables (displays) the cursor (if enable is nonzero) or disables it (if enable is zero). See set_curs_shape. 4-108 Core Functions Set Current Cursor Position set_curs_xy Syntax #include Type Description Core The set_curs_xy function modifies the pixel coordinates of the cursor's hotspot.The cursor coordinates (arguments x and y) are not relative to the drawing origin; they are always relative to the top left-hand corner of the screen. See set_curs_shape. Example 4-109 set_cursattr Set Current Cursor Attributes Syntax #include */ */ */ */ Type Description Core The set_cursattr function changes the display attributes of the current active cursor. Only the attributes for the cursor currently selected are modified. The shape_c and mask_c arguments specify the shape (foreground) and mask (background) colors, respectively. The values specified by these arguments are replicated by the current pixel size before use by the cursor routines. The mask_a and shape_a arguments define the raster op and transparency modes used when drawing the cursor on the screen. Each is a 16-bit value with bit fields defined as follows: Reserved 15 14 13 12 11 10 9 bits 0-4 bit 5 bits 6-15 8 7 6 te 5 4 ppop 3 2 1 0 ppop (see TMS34010 User's Guide, p. 6-13) transparency enable (0=disable,1=enable) reserved for future use Example See set_curs_shape. 4-110 Core Functions Set Foreground Color set_fcolor Syntax #include /* foreground pixel value */ Type Description Core The set_fcolor function sets the foreground color for subsequent drawing operations. Argument color specifies the pixel value to be used to draw foreground pixels. Given a pixel size of N bits, the pixel value is contained in the N LSBs of the argument; the higher order bits are ignored. The function creates a 32-bit replicated pixel value and loads the result into the TMS340 graphics processor's register B9, also referred to as the COLOR1 register. For example, given a pixel size of 8 bits and a pixel value of 5, the replicated pixel value is 0x05050505. Example Use the set_fcolor function to swap the foreground and background colors. #include 4-111 set_interrupt Set Interrupt Handler Syntax #include Type Description Core The set_interrupt function enables/disables a previously installed interrupt service routine. The routine must have been installed via the install_rlm function or the combination of create_alm and install_alm. Argument level indicates the interrupt level where the interrupt routine was installed. When the interrupt is installed, the priority is returned by the get_isr_priorities function 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. Argument scan_line is valid only for display interrupts (interrupt level 10). It is used to set the line at which the interrupt occurs. Argument scan_line is specified in the range of 0 to VTOTAL-1, where VTOTAL is the total number of lines in the frame. Note that a scan_line value of 0 does not necessarily correspond to the top line of the visible screen. For further information, consult the video timing chapter in the TMS34010 or TMS34020 user's guide. If the scan_line argument is -1, then the value for the scan_line is taken to be that passed in the previous invocation of set_interrupt. This allows the interrupt to be enabled/disabled without respecifying the scan_line parameter. The set_interrupt function returns true (nonzero) if the interrupt is set correctly; it returns false (zero) otherwise. For more details on extensibility and the use of this function, see Chapter 8. Example See Section 8.9. 4-112 Core Functions Set State of Loaded Module set_module_state Syntax #include */ */ Type Description Core The set_module_state function is used to set the state of the module specified by the argument module_id. The module identifier returned from the install_rlm and install_alm functions is used as the module_id argument for this function. If you wish to modify the state of the TIGA graphics library module after loading it via the install_primitives function (which does not return a module identifier), use the constant GRAPHICS_LIB_ID provided in the tiga.h, tiga.hch, and tiga.ndp include files as the module_id argument. If an invalid module identifier is passed, or if the module corresponding to the specified module_id is currently not loaded, then the set_module_state function returns FALSE (0). Otherwise, it returns TRUE, indicating no errors. The argument flags contains state information to be assigned to the specified module. These flags are currently supported: Bit 0 0=unlock module / 1=lock module Locking a downloaded module protects it from being flushed whenever the TIGA memory management system is initialized. This initialization occurs when The set_videomode() function is called with either the INIT or INIT_GLOBALS style argument specified, or The gsp_minit() function is called. Conversely, to enable flushing of a previously locked module, the module must first be unlocked by clearing bit 0 of the flags argument and calling the set_module_state function. Bits 1-15 Reserved for future use 4-113 set_module_state Set State of Loaded Module Example #include 4-114 Core Functions Set Multiple Palette Entries set_palet Syntax #include */ */ */ Type Description Core The set_palet function loads multiple palette entries from a specified list of colors. Argument count specifies the number of contiguous palette entries to be loaded. Argument index designates the palette entry at which loading is to begin. Argument palet is an array containing the colors to be loaded into the palette. The palet array must contain at least count elements. The palette entry identified by index is loaded from palet[0], and so on. Argument palet is an array of type PALET. The PALET structure contains the following fields: typedef struct { unsigned char unsigned char unsigned char unsigned char }PALET; r; g; b; i; Refer to the PALET structure description in Appendix A for detailed descriptions of each field. Each array element is a structure containing r, g, b, and i fields. Each field specifies an 8-bit red, green, blue, or gray-scale intensity value in the range 0 to 255, where 255 is the brightest intensity and 0 is the darkest. In the case of a graphics mode for a color display, the r, g, and b fields from each array element are loaded into the red, green, and blue component intensities for the corresponding palette entry; the i field from the element is ignored, and the gray-scale intensity component for the palette entry is set to 0. In the case of a gray-scale mode, the i field from each array element is loaded into the gray-scale intensity value for the corresponding palette entry; the r, g, and b fields from the element are ignored, and the red, green, and blue intensities for the palette entry are set to 0. The range of palette entries to be loaded is checked by the function to ensure that it does not overflow the palette. If the starting index plus the number of entries (count) is greater than the palette size, the function decreases the count value by the appropriate amount. 4-115 set_palet Set Multiple Palette Entries The entire palette may be loaded at once by specifying a count equal to the number of palette entries, and an index of 0. The number of palette entries in the current graphics mode is specified in the palet_size field of the CONFIG structure returned by the get_config function. The 8-bit r, g, b, and i values contained in the palet array are modified by the function to represent the color components or gray-scale intensity actually output by the physical display device. For example, assume that the r, g, b, and i values of a particular array element are specified as follows: r = 0xFF, g = 0xFF, b = 0xFF, and i = 0. If the display hardware supports only 4 bits of red, green, and blue intensity per gun, the values actually loaded into the palette by the set_palet function are r = 0xF0, g = 0xF0, b = 0xF0, and i = 0. In systems that store the palette data in display memory (such as those using the TMS34070 color palette), this function updates the palette area in the frame buffer. If the system contains multiple display pages, the function updates the palette area for every page. Example Use the set_palet function to load a gray-scale palette into the first 16 color palette entries. Use the fill_rect function from the TIGA graphics library to fill a series of rectangles in intensities increasing from left to right. Note that this example requires a color palette with a capacity of at least 16 entries. #include 4-116 Core Functions Set Single Palette Entry set_palet_entry Syntax #include */ */ */ Type Description Core The set_palet_entry function updates a single entry in the color palette. Argument index identifies the palette entry to be updated. Arguments r, g, b, and i specify 8-bit red, green, blue, and gray-scale intensity values in the range 0 to 255, where 255 is the brightest intensity and 0 is the darkest. If the current graphics mode supports a color display, arguments r, g, and b are the red, green, and blue component intensities. In the case of a gray-scale display, argument i is the gray-scale intensity. If the palette contains N entries, the valid range of argument index is 0 through N-1. The number of palette entries in the current graphics mode is specified in the palet_size field of the CONFIG structure returned by the get_config function. If argument index specifies an invalid value, the function aborts (returns immediately) and returns a value of 0; otherwise, it returns a nonzero value. In systems that store the palette data in display memory (such as those using the TMS34070 color palette), this function updates the palette area in the frame buffer. If the system contains multiple display pages, the function updates the palette area for every page. Example Use the set_palet_entry function to load a gray-scale palette into the first 16 color palette entries. Use the fill_rect function from the extended functions library to fill a series of rectangles in intensities increasing from left to right. Note that this example requires a color palette with a capacity of at least 16 entries. #include 4-117 set_pmask Set Plane Mask Syntax #include /* plane mask */ Type Description Core The set_pmask function sets the plane mask to the specified value. The size of the plane mask in bits is the same as the pixel size. Argument pmask contains the plane mask. Given a pixel size of N bits, the plane mask is right-justified in the N LSBs of the argument; the higher order bits are ignored by the function. The plane mask designates which bits within a pixel are protected against writes and affects all operations on pixels. During writes, the 1s in the plane mask designate bits in the destination pixel that are protected against modification, while the 0s in the plane mask designate bits that can be altered. During reads, the 1s in the plane mask designate bits in the source pixel that are read as 0s, while the 0s in the plane mask designate bits that can be read, as is, from the source pixel. The plane mask is set to its default value of 0 during initialization of the drawing environment. The plane mask can be altered with a call to the set_pmask function. The plane mask corresponds to the contents of the TMS340 graphics processor's PMASK register. The effect of the plane mask in conjunction with the pixel-processing operation and the transparency mode is described in the user's guides for the TMS34010 and TMS34020. Example Use the set_pmask function to demonstrate the effects of enabling and disabling particular bit planes. For each bit plane, print a line of text with all but the one plane enabled; print another line of text with only the one plane enabled. This example assumes that the display has at least 4 bit planes --that is, a pixel size of at least 4 bits. 4-118 Core Functions Set Plane Mask set_pmask #include /* defines CONFIG and FONTINFO /* minimum pixel size */ */ init_tiga(0); clear_screen(-1); get_config(&cfg); get_fontinfo(-1, &fntinf); x = y = 10; for (pmask = 1; pmask != 1< set_ppop Set Pixel-Processing Operation Code Syntax #include /* pixel processing operation code */ Type Description Core The set_ppop function specifies the pixel-processing operation to be used for subsequent drawing operations. The specified Boolean or arithmetic operation determines the manner in which source and destination pixel values are combined during drawing operations. Argument ppop is a pixel-processing operation code in the range of 0 to 21. The PPOP code is right-justified in the 5 LSBs of the argument; the higher order bits are ignored by the function. Legal PPOP codes are in the range of 0 to 21. The source and destination pixel values are combined according to the selected Boolean or arithmetic operation, and the result is written back to the destination pixel. As shown in Table 4-2, Boolean operations are in the range of 0 to 15, and arithmetic operations are in the range of 16 to 21. Table 4-2.Pixel-Processing Operations PPOP Code 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 Description replace destination with source source AND destination source AND NOT destination set destination to all 0s source OR NOT destination source EQU destination NOT destination source NOR destination source OR destination destination (no change) source XOR destination NOT source AND destination set destination to all 1s NOT source OR destination source NAND destination NOT source source plus destination (with overflow) source plus destination (with saturation) destination minus source (with overflow) destination minus source (with saturation) MAX(source, destination) MIN(source, destination) When the drawing environment is initialized, the PPOP code is set to its default value of 0 (replace operation). The PPOP code can be read with a call to the get_ppop function. 4-120 Core Functions Set Pixel-Processing Operation Code set_ppop The pixel-processing operation code corresponds to the 5-bit PPOP field in the TMS340 graphics processor's CONTROL register. The effects of the 22 different codes are described in more detail in the user's guides for the TMS34010 and TMS34020. Example Use the set_ppop function to set the current pixel-processing operation code to 10 (exclusive-OR ). Use the fill_rect function from the TIGA graphics library to fill two rectangles that partially overlap. The overlapping region shows the effect of exclusive-ORing identical source and destination pixel values. #include /* pixel processing operation code */ 4-121 set_text_xy Set Text x-y Position Syntax #include /* text x-y coordinates */ Type Description Core The set_text_xy function sets the text-drawing position to the specified x-y coordinates. This is the position at which the next character (or string of characters) will be drawn if a subsequent call is made to the text_outp function. Both the text_outp and text_out functions automatically update the text position to be the right edge of the last string output to the screen. Arguments x and y are the coordinates of the new text position on the screen, specified relative to the current drawing origin. Argument x is the x coordinate at the left edge of the next string output by the text_outp function. Argument y is the y coordinate at either the top of the string or the base line, depending on the state of the text alignment attribute (see the description of the set_textattr function). Example Use the set_text_xy function to set the text-drawing position to x-y coordinates (10, 20). Use the text_outp function to print a text string to the screen starting at these coordinates. #include 4-122 Core Functions Set Timeout Delay Value set_timeout Syntax #include /* value in milliseconds */ Type Description Host-only The set_timeout function sets the timeout value (in milliseconds) that determines how long the host waits for a TMS340 function to complete before calling the error function with a timeout error. 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. See install_usererror. Example 4-123 set_transp Set Transparency Mode Syntax #include /* transparency mode */ Type Description Core The set_transp function, if implemented, changes the transparency mode. When transparency is enabled, this mode determines how a pixel is defined as transparent. During a graphics output operation, a nontransparent pixel replaces the original destination pixel, but a transparent pixel does not. The set_transp function is implemented only on TMS34020 systems. Currently, the modes supported on TMS34020 systems are mode = 0 mode = 1 mode = 5 Transparent if result equal to zero Transparent if source equal to COLOR0 Transparent if destination equal to COLOR0 Argument mode must be set to one of these values. Specifying an invalid mode number may result in undefined behavior. On TMS34010 systems, the set_transp function is not implemented, and only transparency mode 0 is supported. The enabling and disabling of transparency, regardless of the mode selected, is performed by two other functions, transp_on and transp_off. Refer to the descriptions of these functions for more information. Immediately after initialization of the drawing environment, the system is configured in transparency mode 0, which is the default. 4-124 Core Functions Set Contents of TMS340 Trap Vector set_vector Syntax #include Type Description Core The set_vector function loads one of the TMS340 graphics processor's trap vectors with a pointer to a location in the processor's memory. This function provides a portable means of loading the entry point to a trap service routine, regardless of whether the actual trap vector is located in RAM or ROM. Argument trapnum specifies a trap number in the range of -32768 to 32767 for a TMS34020, and in the range of 0 to 31 for a TMS34010. Argument gptr is a pointer containing the 32-bit memory address to be loaded into the trap vector. The value returned by the function is the original 32-bit TMS340 graphics processor address contained in the designated trap vector at the time of the call. 4-125 set_videomode Set Video Mode Syntax #include Type Description Host-only The set_videomode function sets up the video mode to be used. Every TIGA application should call this function (after calling tiga_set to initialize the TIGA environment), with a mode of TIGA, before invoking any other TIGA function. The following values, provided in tiga.h, are valid mode arguments: TIGA OFF_MODE PREVIOUS MDA HERCULES CGA VGA AI_8514 EGA TIGA is a high-resolution mode supported by the board. OFF_MODE is used on systems that provide no videomode for the DOS screen (such as EGA); when not running TIGA, such boards are in the OFF_MODE. PREVIOUS is the mode that the board was in before the current mode. All the other modes (MDA, HERCULES, CGA, etc.) provide the graphics modes for DOS. They are either provided by separate hardware or are emulated by the TMS340 processor. All TIGA applications should call set_videomode with TIGA mode upon starting. They should then call set_videomode again at the end of their program to restore the video mode (since in many cases the board on which TIGA is being run is not the primary video board). The mode selected could be PREVIOUS, which restores the mode set in the last call to set_videomode. However, if a particular application wants to switch back and forth between several modes, it is recommended that a call be made to get_videomode and that 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 set_videomode specifying a video mode not supported by the board, the function returns false (0). Otherwise, it returns true (1), indicating successful completion. The style argument is used to determine the manner in which the mode is set up on entry. These are the valid styles: NO_INIT Used during an application to switch between TIGA and other modes. It enters TIGA, leaving all global variables intact. INIT_GLOBALS Initializes the global variables only, by calling set_config with the init_draw flag true and by restoring the timeout val4-126 Core Functions Set Video Mode set_videomode INIT INIT_GM ue and the user error handler. The heap pool is retained, which keeps any downloaded extensions installed. Initializes global variables and dynamic memory (heap pool).This frees all allocated pointers and thus deletes all unsecured downloaded extensions. Forces the TIGA Graphics Manager to be reloaded, initializes GM global variables, and frees all allocated pointers and downloaded TIGA extensions. The state of the graphics manager is checked by the set_videomode function with a mode of TIGA. If the graphics manager is not loaded or is corrupted and the specified style argument is INIT or INIT_GLOBALS, set_videomode loads and executes it. The style argument contains two additional options, which can be selected by ORing with the above style parameter: CLR_SCREEN Clears the screen with zeros when specified. It should be specified at initialization when you are using the INIT_GLOBALS or INIT styles. The screen is blanked while the video registers are initialized. Note that all display memory is cleared to 0 (including any offscreen areas) when specifying CLR_SCREEN. In other words, specifying CLR_SCREEN is functionally equivalent to calling the clear_frame_buffer() function. NO_ENABLE This parameter inhibits switching the video output from the current mode to TIGA. It is valid only when TIGA is specified as the mode argument. For example, assuming a single monitor configuration and a current video mode of VGA, calling set_videomode(TIGA, INIT | NO_ENABLE) would enable you to call any TIGA core function but would not switch the video output from the VGA board to the TIGA board. Example See the init_tiga and term_tiga function listings in Section 3.4, page 3-6. 4-127 set_windowing Set Window-Clipping Mode Syntax #include Type Description Core The set_windowing function loads the specified value into the 2-bit windowing field contained in the CONTROL I/O register. The four windowing modes are 1) 002 2) 012 3) 102 4) 112 No windowing. Interrupt request on write in window. Interrupt request on write outside window. Clip to window. Take care in using this function. TIGA's drawing functions assume that the TMS340 graphics processor is configured in windowing mode 3. Changing the windowing mode from this default may result in undefined behavior of the extended graphics library functions. The code specified for the window-clipping mode corresponds to the 2-bit W field in the TMS340 graphics processor's CONTROL register. The effects of the W field on window-clipping operations are described in the user's guides for the TMS34010 and TMS34020. Immediately following initialization of the drawing environment, the system is configured in windowing mode 3, which is the default. 4-128 Core Functions Set Workspace Information set_wksp Syntax #include Type Description Core The set_wksp function specifies an offscreen workspace. None of the current TIGA core or extended functions makes use of this workspace; it is provided to support future graphics extensions that require storage for edge flags or region-of-interest masks. Argument addr is the base address of the offscreen workspace. Argument pitch is the difference in memory addresses of two adjacent rows in the offscreen workspace. The pitch is required to be a power of two and a multiple of 16. The exception to this requirement is that the pitch argument is specified as 0 in the event that no workspace is allocated (in which case, the value of the addr argument is a don't care.) The offscreen workspace is a 1-bit-per-pixel bit map of the same width and height as the screen. If the display hardware provides sufficient offscreen memory, the workspace can be allocated statically. By convention, the workspace pitch retrieved by the get_wksp function is nonzero when a workspace is allocated; following initialization the pitch can be checked to determine whether a workspace is statically allocated. The workspace can be allocated dynamically by calling the set_wksp function with the address of a valid workspace in memory and a nonzero pitch; it can be deallocated by calling set_wksp with a pitch of 0. Not all TMS340 graphics processor-based display configurations may contain sufficient memory to allocate (statically or dynamically) an offscreen workspace. For this reason, proprietary extensions to the core functions library that require use of the workspace may be unable to execute on some systems. 4-129 setup_hostcmd Initialize Call-Back Environment Syntax #include */ Type Description Host-only The setup_hostcmd function initializes the TIGA call-back environment, enabling host-resident functions to be called from the TMS340 processor. The argument hinit is a far pointer to a structure of type HOST_INIT. The elements of this structure are defined in the typedefs.h include file. No value is returned by this function. See Section 8.8, page 8-31, for detailed information on how to use this and other functions related to the TIGA call-back feature. 4-130 Core Functions Flush Relocatable Load Module Symbols sym_flush Syntax #include Type Description Core The sym_flush function flushes the symbols associated with the module specified by the argument module_id. Argument module_id is returned by the install_rlm or install_alm function when the module is loaded. Use the module_id GRAPHICS_LIB_ID provided in the tiga.h, tiga.hch, and tiga.ndp include files to specifiy the TIGA extended graphics library module. If module_id is -1, then the symbols associated with all unsecured installed modules are flushed. The TIGA graphics manager and core function symbols are retained. The function returns true (1) if the symbols were flushed successfully. A return value of false (0) indicates an error, caused by either of these conditions: a module_id is invalid, or the module specified by module_id is not loaded or is secured. Flushing symbols frees TMS340 memory, increasing the memory available for allocation by the TIGA application. However, installing at a later time any userextended module that references previously flushed symbols results in a symbol-referencing load error. 4-131 synchronize Synchronize Host and TMS340 Communications Syntax #include Type Description Host-only The synchronize function ensures that the TMS340 completes all pending operations before it returns. TIGA supports two-processor execution, and some conditions require the two processors 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. See install_usererror. Example 4-132 Core Functions Render ASCII String text_out Syntax #include */ */ Type Description Core The text_out function draws a character string to the screen in the currently selected font. Arguments x and y are the starting coordinates of the string, relative to the current drawing origin. Argument s is a string of 8-bit ASCII characters terminated by a null (0) character. The string is rendered in the currently selected font using the current text-drawing attributes. Argument x is the x coordinate at the left edge of the string. Argument y is the y coordinate at either the top of the string or the base line, depending on the state of the text alignment attribute. During initialization of the drawing environment, the alignment is set to its default position at the top left corner. The attribute can be modified by means of a call to the set_textattr function. 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. Example Use the text_out function to write a single line of text to the screen in the system font. #include 4-133 text_outp Render ASCII String at Current x-y Position Syntax #include Type Description Core The text_outp function outputs text to the screen, starting at the current text drawing position. The specified string of characters is rendered in the currently selected font and with the current text-drawing attributes. The text position must have been specified by a previous call to the set_text_xy, text_out, or text_outp function. Argument s is a string of 8-bit ASCII character codes terminated by a null (0) character. After printing the text on the screen, the function automatically updates the text position to be the position of the next character to the right of the string just printed. A subsequent call to the text_outp function will result in the next string being printed, beginning at this position. Unlike the text_out function, the text_outp function does not return a value. Example Use the text_outp function to mix two fonts --TI Roman size 20 and TI Helvetica size 22 --in the same line of text. Use the set_textattr function to align the text to the base line. Note that the function loadinst_font is called to load and install a TIGA font from a font file. The loadinst_font is not a TIGA function but does make calls to various TIGA functions to load a font. Refer to the install_font function description in Chapter 5 for a complete source listing of the loadinst_font function. #include 4-134 Core Functions Determine if TIGA Is Busy tiga_busy Syntax #include Type Description Host-only The tiga_busy function returns a status code indicating whether TIGA is immediately ready to process a host-initiated TIGA command. If so, 0 is returned. However, if TIGA is busy,1 is returned. When a host application calls a TIGA core or extended function, the function request is queued up in the communication buffer queue. This queue is serviced by the TIGA graphics manager (GM), which pulls the function request information out of the buffer and executes the specified command. There may be instances when the GM cannot service the functions as fast as the host is requesting them. In this case, the TIGA communication driver (CD, on the host side of TIGA) waits until a free communications buffer is available, before writing the requested function information and returning control to the application. You may find this dead time useful for performing other tasks while the GM is processing queued commands. Note that host-only TIGA functions are always executed immediately by the CD. Thus, the return value of tiga_busy is valid only for core or extended functions. 4-135 tiga_set Open/Close/Query Communication Driver Syntax #include /* Mode or command */ Type Description Host-only The tiga_set function initializes communications with the TIGA communications driver and sets up the TIGA device to a known state. It should be the first function called in a TIGA application. The mode argument specifies the state of the TIGA communication driver or requests that information relating to the current TIGA environment be returned. These are valid values for the mode argument: mode = CD_OPEN (1) Initialize the TIGA communication driver. If a protected mode TIGA environment is required (that is, the TIGA application is running in protected mode), this is also initialized. Valid return values are 0 -4 -25 Initialization OK TIGA CD is not installed TIGA board communications init failure mode = CD_CLOSE (0) Restore the PC environment to that before tiga_set(CD_OPEN) was called. Valid return values are 0 -26 Success TIGA CD was not open mode = CD_STATUS (2) Return information about the current TIGA CD environment in the 32-bit return value as follows: Bit 0 Bit 1 Bit 2 Bits 3-15 Bits 16-23 Bits 24-31 CD State: 0=closed / 1=open CD operating mode: 0=Real / 1=Protected mode CD communications: 0=Polled / 1=HW interrupt Reserved TIGA CD Minor revision level TIGA CD Major revision level 4-136 Core Functions Open/Close/Query Communication Driver tiga_set The tiga_set function is new to TIGA 2.0. In previous versions of TIGA, the TIGA environment became active when a call to cd_is_alive was executed, and it remained active until the application terminated. Most applications activated the TIGA environment through calls to set_videomode, which indirectly executed the function cd_is_alive. Calling any other TIGA function before calling tiga_set(CD_OPEN) results in an error return. In addition, the cd_is_alive function is no longer available to the application developer, because its functionality is a subset of the tiga_set function. Note that applications linked with the TIGA 1.1 AI library are not affected by the addition of the tiga_set function. Example See the init_tiga and term_tiga function listings in Section 3.4, page 3-6. 4-137 transp_off Turn Transparency Off Syntax #include Type Description Example Use the transp_off function to demonstrate the effect of disabling transparency. Use the draw_rect function from the TIGA graphics library to construct a background pattern. To show that the background pattern is preserved in the rectangle surrounding each character, use the text_out function to draw a line of text to the screen with transparency enabled. Also, draw a line of text to the screen with transparency disabled to show that the background pattern is overwritten. #include 4-138 Core Functions Turn Transparency On transp_on Syntax #include Type Description Core The transp_on function enables transparency for subsequent drawing operations. Transparency is an attribute that affects drawing operations. Several transparency modes are supported. During initialization of the drawing environment, transparency is disabled, and the transparency mode is set to the default, mode 0. The TMS34010 supports only transparency mode 0, but the TMS34020 supports additional modes. Refer to the description of the set_transp function for details. In transparency mode 0, if transparency is enabled and the result of a pixelprocessing 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. For instance, to avoid modifying destination pixels in the rectangular region surrounding each character shape, you can enable transparency before you call the text_out or text_outp function. The effect of transparency in conjunction with the pixel-processing operation and the plane mask is described in the user's guides for the TMS34010 and TMS34020. Example Use the transp_on function to demonstrate the effect of enabling transparency. Use the draw_rect function from the TIGA graphics library to construct a background pattern. To show that the background pattern is overwritten in the rectangle surrounding each character, use the text_out function to draw a line of text to the screen with transparency disabled. Also, draw a line of text to the screen with transparency enabled to show that the background pattern is preserved. #include 4-139 wait_scan Wait for Scan Line Syntax #include /* scan line number */ Type Description Core The wait_scan function waits for the monitor to scan a designated line on the screen. Argument line is the scan line number. Scan lines are numbered in ascending order, starting with line 0 at the top of the screen. Given a display of N lines, valid arguments are in the range of 0 to N-1. 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. The number of scan lines on the screen in the current graphics mode is specified in the disp_vres field of the CONFIG structure returned by the get_config function. Once the function is called, it does not return control to the calling routine until the designated line is scanned by the monitor's electron beam. Control is returned at the start of the horizontal blanking interval that follows the scan line. This function is used to synchronize drawing operations with the position of the electron beam on the monitor screen. For example, when an animated sequence of frames is being drawn, transitions from one frame to the next appear smoother if an area of the screen is not being drawn at the same time it is being scanned on the monitor. The wait_scan function is typically used to achieve a limited degree of smooth animation in graphics modes that provide only a single video page (or frame buffer). The page_flip and page_busy functions support double buffering in modes that provide more than one page. Double buffering, when available, is usually preferred for animation applications. Example Use the wait_scan function to smoothly animate a rotating asterisk. The position of the asterisk is updated once per frame. Before drawing the asterisk in its updated position, the wait_scan function is utilized to delay erasing the asterisk until the area just beneath it is being scanned. The asterisk is erased by overwriting it with a space character. This technique works well with the system font, which is a block font, but might produce unexpected results if used with a proportionally spaced font. 4-140 Core Functions Wait for Scan Line wait_scan #include /* defines FONTINFO structure /* radius of revolution */ */ init_tiga(0); clear_screen(-1); get_fontinfo(-1, &fntinf); x = (long)RADIUS << 16; y = 0; i = j = 0; do { wait_scan(j+fntinf.charhigh); text_out(i, j, " "); i = RADIUS + (x >> 16); j = RADIUS + (y >> 16); text_out(i, j, "*"); x - = y >> 4; y + = x >> 4; }while(!kbhit()); getch(); term_tiga(); } 4-141 4-142 Core Functions Chapter 5 Extended Graphics Library Functions This chapter discusses the extended functions alphabetically. Each discussion Shows the syntax of the function declaration and the arguments that the function uses. Contains a description of the function operation, which explains input arguments and return values. Provides an example of the use of some functions. Before you use the functions described in this chapter, you must first install them by calling the install_primitives function, described on page 4-82. The examples in this chapter use the functions init_tiga and term_tiga to initialize and terminate the TIGA environment. Although the init_tiga and term_tiga functions are not actually TIGA functions, they do make calls to various TIGA functions.The init_tiga function initializes the TIGA environment and is called before any other TIGA function. The term_tiga function terminates a TIGA application by restoring the previous video mode and closing the TIGA communication driver. Refer to Section 3.4, page 3-6, for a sample TIGA application that illustrates the init_tiga and term_tiga functions. 5-1 Extended Graphics Library Functions 5.1 Extended Graphics Library Functions The following is an alphabetical table of contents for functions reference. Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page bitblt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 decode_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 delete_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 draw_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11 draw_oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12 draw_ovalarc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 draw_piearc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15 draw_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17 draw_polyline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18 draw_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20 encode_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21 fill_convex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 fill_oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27 fill_piearc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28 fill_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30 fill_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32 frame_oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33 frame_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34 get_env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35 get_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-37 get_textattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-38 in_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40 install_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-41 move_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-43 patnfill_convex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-44 patnfill_oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-46 patnfill_piearc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47 patnfill_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-49 patnfill_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-51 patnframe_oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-52 patnframe_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-54 patnpen_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-56 patnpen_ovalarc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-57 patnpen_piearc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-59 patnpen_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-61 patnpen_polyline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-62 pen_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-64 pen_ovalarc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-65 pen_piearc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-67 pen_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-69 pen_polyline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-70 put_pixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-72 seed_fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-73 seed_patnfill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-75 select_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-77 set_draw_origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-78 set_dstbm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-79 set_patn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-81 5-2 Extended Graphics Library Functions Extended Graphics Library Functions set_pensize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_srcbm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_textattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . styled_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . styled_oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . styled_ovalarc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . styled_piearc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . swap_bm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . text_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zoom_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-83 5-84 5-86 5-88 5-90 5-92 5-94 5-96 5-97 5-98 5-3 bitblt Syntax Transfer Bit-Aligned Block #include */ */ */ Description The bitblt function copies a two-dimensional array of pixels from the current source bitmap to the current destination bit map. The source and destination bitmaps are specified by calling the set_srcbm and set_dstbm functions before calling the bitblt function. Calling the set_videomode function with the style argument set to INIT or INIT_GLOBALS causes both the source and destination bitmaps to be set to the default bitmap, which is the screen. The source and destination arrays are assumed to be rectangular, two-dimensional arrays of pixels. The two arrays are assumed to be identical in width and height. The bitblt function accepts source and destination arrays that have the same pixel size. If the pixel sizes are not equal, the pixel size for either the source or the destination must be 1. Other combinations of source and destination pixel sizes are not accepted by the function. Arguments w and h specify the width and height common to the source and destination arrays. Arguments xs and ys specify the x-y coordinates of the top left corner (lowest memory address) of the source array as a displacement from the origin (base address) of the source bitmap. Arguments xd and yd specify the x-y coordinates of the top left corner of the destination array as a displacement from the origin of the destination bitmap. If the source and destination pixel sizes are equal, then pixels in the source array are copied to the destination. During the copying process, the pixels may be modified, depending on the current pixel-processing operation, transparency mode, and plane mask. If the source bitmap's pixel size is 1 and the destination pixel size is greater than 1, source pixels are expanded to color in the destination array. During the expansion process, pixels corresponding to 1s in the source bitmap are expanded to the current foreground color before being drawn to the destination; 0s are expanded to the current background color. If the destination bitmap's pixel size is 1 and the source pixel size is greater than 1, bitblt performs a contract function on the source before writing to the destination. During the contraction process, destination pixels are set to 0 if they correspond to source pixels that are equal to the background color; all other destination pixels are set to 1. 5-4 Extended Graphics Library Functions Transfer Bit-Aligned Block bitblt When the source or destination bitmap is the screen, the specified source or destination coordinates are defined relative to the current drawing origin. In the case of a linear bitmap contained in an off-screen buffer, the bitblt function calculates the memory address of a pixel from the specified x and y coordinates as follows: address = baseaddr + y*(pitch) + x*(psize) where baseaddr, pitch, and psize are the argument values passed to the set_dstbm or set_srcbm function. When the destination bitmap is set to the screen, the function clips the destination bitmap to the current rectangular clipping window. When the source bitmap is set to the screen and any portion of the source array lies in negative screen coordinate space, the source rectangle is clipped to positive x-y coordinate space; in most systems this means that the source is clipped to the top and left edges of the screen. The resulting clipped source rectangle is copied to the destination rectangle and justified to the lower right corner of the specified destination rectangle. Portions of the destination array corresponding to clipped portions of the source are not modified. The clipping window for a linear bitmap encloses the pixels in the x-y coordinate range (0,0) to (xext, yext), where xext and yext are arguments passed to set_dstbm or set_srcbm. The bitblt function itself performs no clipping in the case of a linear bitmap; responsibility for clipping is left to the calling routine. If both source and destination bitmaps are set to the screen, then the function correctly handles the case in which the rectangular areas containing the source and destination bitmaps overlap. In other words, the order in which the pixels of the source are copied to the destination is automatically adjusted to prevent any portion of the source from being overwritten before it has been copied to the destination. Example Use the bitblt function to color-expand an image contained in a 1-bit-per-pixel bitmap to the screen. The original image is 16 pixels wide and 40 pixels high; it has a pitch of 16. Use the zoom_rect function to zoom the screen image by a factor of 5. #include 0x00F00, 0x01FC0, 0x0FFFC, 0x0FFE0, 0x03DE0, 0x01F80, 0x07FE0, 0x0FFFC, 0x0BFE0, 0x03DE0, 0x07FC0, 0x0FFF0, 0x0FFFC, 0x0BDE0, 0x03DE0, 0x031F0, 0x0FFF8, 0x0FFFC, 0x07DE0, 0x03DE0, 0x010C0, 0x0FFF8, 0x0FFF8, 0x03DE0, 0x03DE0, 0x01080, 0x0FFFC, 0x0FFF8, 0x03DE0, 0x03DE0, 0x00880, 0x0FFFC, 0x0FFB8, 0x03DE0, 0x07DF0, 0x00700, 0x0FFFC, 0x0FFD0, 0x03DE0, 0x0F8F8 }; 5-5 bitblt Transfer Bit-Aligned Block main() { PTR image_ptr, rowbuf; CONFIG c; init_tiga(1); clear_screen(0); /* Allocate memory for image image_ptr = gsp_malloc(sizeof(image)); /* Copy image to TMS340 memory host2gsp(image, image_ptr, sizeof(image), 0); /* Set source bitmap to image set_srcbm(image_ptr, PITCH, W, H, IMAGEDEPTH); /* Blit image to screen bitblt(W, H, 0, 0, 10, 10); /* Set source bitmap to screen set_srcbm(0, 0, 0, 0, 0); get_config(&c); rowbuf = gsp_malloc((c.mode.disp_hres * c.mode.disp_psize) / 8); zoom_rect(W, H, 10, 10, ZOOM*W, ZOOM*H, 20+W, 10, rowbuf); term_tiga(); } */ */ */ */ */ 5-6 Extended Graphics Library Functions Decode Rectangular Image decode_rect Syntax #include */ */ Description The decode_rect function restores a previously compressed image to the screen. The image was previously encoded by the encode_rect function. The image is rectangular and is restored at the same width, height, and pixel size as the image originally encoded by the encode_rect function. The first two arguments, xleft and ytop, specify the x and y coordinates at the top left corner of the destination rectangle and are defined relative to the drawing origin. The final argument, buf, is a pointer to a buffer in the TMS340 graphics processor's memory in which the compressed image is stored. The function returns a nonzero value if it has successfully decoded the image; otherwise, the return value is 0. Refer to the description of the encode_rect function for a discussion of the format in which the compressed image is saved. Example Use the decode_rect function to decompress multiple copies of a rectangular image that was previously captured from the screen by the encode_rect function. #include main() { short w, h, x, y, n; char *s; PTR image; init_tiga(1); clear_screen(-1); 5-7 decode_rect Decode Rectangular Image /* Create an image on the screen w = 100; h = 80; x = 10; y = 10; frame_rect(w, h, x, y, 4, 3); frame_oval(w-8, h-6, x+4, y+3, 4, 3); s = "IMAGE"; n = text_width(s); text_out(x+(w-n)/2, y+h/2, s); image = gsp_malloc(MAXSIZE); /* Compress image encode_rect(w, h, x, y, image, MAXSIZE, 0); /* Now decompress the image several times for (n = x ; n <= x + w; n += 16) decode_rect(n, n, image); term_tiga(); } */ */ */ 5-8 Extended Graphics Library Functions Remove a Font From Font Table delete_font Syntax #include */ Description The delete_font function removes from the font table the installed font designated by an identifier. The font is identified by argument id, which contains the value returned from the install_font function at the time the font was installed. A nonzero value is returned if the font was successfully removed. A value of 0 is returned if argument id is invalid; that is, if id does not correspond to an installed font. If the font removed was also the one selected for current text drawing operations, the system font is automatically selected by the function. A request to delete the system font (id = 0) will be ignored by the function, and a value of 0 will be returned. Example Use the delete_font function to delete a font that was previously installed. First, install and select three fonts. The first and third fonts installed by the example program are proportionally spaced fonts. The second font is a block font. The three fonts are used to write three lines of text to the screen. At this point, the block font is deleted with the delete_font function, and another proportionally spaced font is installed in its place. An additional three lines of text are written to the screen via the three installed fonts. Note that the function loadinst_font is called to load and install a TIGA font from a font file. The loadinst_font is not itself a TIGA function but does make calls to various TIGA functions to load a font. Refer to the install_font function description on page 5-41 for a complete source listing of the loadinst_font function. #include */ */ */ main() { FONTINFO fontinfo; short index[NFONTS]; short i, j, x, y; 5-9 delete_font Remove a Font From Font Table init_tiga(1); clear_screen(0); index[0] = loadinst_font("ti_rom11.fnt"); /* install block font index[1] = loadinst_font("sys16.fnt"); index[2] = loadinst_font("ti_rom16.fnt"); x = y = 10; for (i = 0; i < 2; i++) { for (j = 0; j < NFONTS; j++) { select_font(index[j]); get_fontinfo(index[j], &fontinfo); text_out(x, y, "Output text in new font."); y += fontinfo.charhigh; } y += fontinfo.charhigh; delete_font(index[1]); /* delete block font index[1] = loadinst_font("ti_rom14.fnt"); } term_tiga(); } */ */ 5-10 Extended Graphics Library Functions Draw Straight Line draw_line Syntax #include |