C/C++ Interactive Guide

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource4 / 227_01 / graf.txt < prev next >

Wrap

Text File | 1988-02-09 | 89.8 KB | 3,829 lines

Compatible graphics library Public Domain Compatible Graphics Library The C User's Group Author Rainer Gerhards Petronellastr. 6 D-5112 Baesweiler West Germany Library Version 2.1, 11/15/1987 Documentation Version 2.1 (11/15/87 16:56:50) supported operating systems MS-DOS or PC-DOS 2.0 or higher supported C compilers Lattice C 3.0 Datalight C 2.23 Borland Turbo C 1.0 [Microsoft C] supported graphics cards Hercules monochrome graphics card enhanced graphics adapter (EGA) IBM std. BIOS interface Elsa PC XXHR vector graphics board supported graphics printer Nec pinwriter P6 / P7 Epson TM compatible printers supported plotters --- currently none --- Page 1 Compatible graphics library This document describes the compatible graphics library for almost every (strong words, I know) computer. Everybody is free to copy, adapt or modify the listed sources and documentation. It would be nice, if you copy this acknowledgment and the authors name and address too. If you have new ideas or improvements please contact the author. Page 2 Compatible graphics library 1. Introduction 1.1 Design_history_and_background This library was first designed as a demonstration library for very fast assembly language routines. But after a while using it, I think that this C library is much more powerful than the assembly language library is. Ok, the assembly language library is somewhat faster, but it hasn't the ability to run on all well-known graphics devices for the IBM PC. And I think it will be a horrible task to port the library to a really different environment - an Unix machine for example. This is a much more easy task with the C language library. So this C library builds the base of a compatible graphics system, which will run on a CP/M machine as well as on a big Unix system. Currently only parts of the IBM personal computer hardware are supported, because I own no other hardware. I hope, that other users will help to make this library really portable and powerful. While the first version implemented only the basic tasks, the current version (2.1) has many intersting features and is greatly enhanced above version 1.1. It is very nice to move from one video device to another without source-code changes. I also improved the speed and memory requirements of the library dramatically, and so I think this version covers a lot of serious projects. I hope that some of you have some interesting ideas and algorithms and want to tell me about them. So I hope to get a full praxis-driven library. In addition, I hope that some of you want to port the low-level parts of the library to different machines and graphics environments, making the library really portable. Everybody should feel free to contact me! 1.2 Current_features The most powerful feature of the library is its compatibility and hardware independency. You may use the library on many machines, as long as there's driver available. And new drivers can be very simply added. The library currently supports: - switching between different display modes (graphics/nongraphics) - drawing pixels Page 3 Compatible graphics library - drawing lines - drawing polylines - drawing boxes - filling boxes with given colors (e.g. clear windows) - draw any ellipses in full or in part - paint any region on the screen with a given color. The region is defined by a border color. - you may use a global coordinate system, freeing you from the given hardware parameters. Also very useful in numerical applications. - print graphics screens as a hardcopy function. This is currently limited to the Hercules graphics card and Epson compatible printers. - clear the graphics screen. - read the color of a specified pixel. - output text in different styles with user selectable foreground and background colors. - use a library error-code system. Errors occurred while processing graphics Information may be printed with a function like perror. - a full turtle graphics system - different device write modes. New drawing may be modifyed according to the old video contents (XOR them, e. g.). 1.3 new_features_and_enhancements_of_version_2.1 The following new features, enhancements and bug fixes have been applied to the library since version 2.1: - A bug in the medium-level header file has been fixed. The EGA-mode was defined in this header file, resulting in bad coding sequences for devices other than EGA. This define has been moved to the right place in the EGA low-level header file. Note that the version 1.1 distribution disk was corrupted by this bug. Page 4 Compatible graphics library - A bad bug in herc.c, the C-part of the hercules low- level driver has been detected and removed. Mr. Decker of Nuernberg, West Germany reported my, that the given port address in this low-level driver were incorrect. As a result, the switch into the hercules graphic mode was unsuccessful. I'm sorry, the Hercules emulation I use on the QuadEGA switched always correctly to graphics mode, so I don't saw an error. Sorry to all Hercules users who only saw a black screen! This bug has been corrected (two addresses, dammed!). - The low-level driver for the Hercules graphics card and the EGA have been greatly improved and speeded up. New internal function calls have been added, resulting in a great speedup of the whole library code. This effect is extreme in function paint and line. - The hercules low-level driver has a much better hardcopy routine. The new routine optimizes the print- output before sending it to the printer, resulting in a great decrease of print-time, if the screen is nearly blank. The more information is presented on the graphics screen, the less the decrease of print time will be, but I think it's really good for many applications. - The stack space needed by function paint has been dramatically reduced. It now requires only about 20% of the original space. Also the processing time has been reduced. - The assembly language macros have been implemented. Version 1.1 used the Lattice macros, which couldn't be distributed due to copyright limitations. The now written macro package implements all used Lattice macros in a manner, that makes moving to a new compiler an relatively easy task. Also some macros have been defined for this reason, which weren't implemented in the Lattice package. You may find the macro package also of interest for your own assembly language routines, the documentation should be good enough to use them. They are not documented as part of the library, because their internal implementation is not guaranteed to be the same in the next release. Nevertheless, there are some parameters the user must set to correct assemble the sources. This parameters are described below. - A new set of parameters have been added to the medium- /high-level header file "graphics.h". These parameters allows it the user to modify some minor configuration Page 5 Compatible graphics library parameters. The usage of this mechanism will be described below. - The text-output system has been added. It is currently not complete implemented, but offers a good chance to do most text-output jobs. - The new function polyline has been added. It allows the user to draw a complex figure or line with only one function call. It is able to work on a variable table which holds line coordinates. All the coordinates are concatenated with a user-specified color. - An error system has been implemented. Functions, which may detect error conditions return -1 if an actual error occurred, 0 otherwise. In case of an error return, the global variable "gr_error" may be examined for the exact error reason. The function "grperror" has been added to print the error message in a human- readable form. It is much like perror, but with increased functionality. The error system is described in greater detail below. - A complete turtle graphics system has been added. This system supports all of the common turtle graphics commands including turtle positioning, moving and hiding/showing. This package is described below in more detail. - A new, powerful feature has been added: You now can specify an so-called write mode. This write mode is applied to all pixel drawing operations. It allows you to modify the display contents in respect to its old state. E. g. the old pixel color may be XORed with the new color. - A basic-equivalence header file has been added. This allows it user's who like the basic names for some graphics primitives to use them, without destroying compatibility to users (and library versions), who do not. This feature is an idea of Michael Yokoyama of Aiea, HI 96701. - Some documentation bugs have been fixed and the whole documentation has been upgraded to reflect the latest version of the library. - The whole library is now maintained internally by Unix SCCS, so the SCCS version numbering scheme has been adapted. All version numbers are now starting at one. Page 6 Compatible graphics library The old version 1.1 has been renamed to 1.1. - Some minor bugs have been fixed. 1.4 Release_compatibility The graphics library is upward compatible. This means, that programs that used version 1.1 of the library will run without modification using version 2.1 of the library. Note that not all 2.1 functions are supported by version 1.1 of the library, so you can not move user code from 2.1 to 1.1. Even if it may be possible (no extended functionality used), you should always use the latest version of the library because of bug fixes and execution speed. When moving form version 1.1 to 2.1, you need not to recompile the user code if you don't need the extended functionality. Note that low-level drivers written for Version 1.1 of the library are still functional under 2.1. If this are assembly language drivers, they should be upgraded to use the new macro support facility. This easies the task to move them to other compilers. 2. Library_design The library uses three logical parts: one medium-level, completely machine independent graphics kernel, a medium- level machine-independent part and one low-level machine dependent part. There are header (.h) files for the high- and low-level parts. The user program hasn't to know which function resides in which part of the graphics library. If it uses the official entry points, it must be portable to any new video device, if it's supported by the library. The available entry points are listed under "User program interface". 2.1 High-level_library_part The high-level library part is completely hardware and operating system independent. It's written entirely in C. It contains all the more complex drawing operations based on the medium- and low-level part. There's no need to recompile the high-level part for the different video devices. This makes it possible to use loadable device drivers, which allows dynamically reconfiguration of the user-program for different video devices - all at runtime without recompilation. Page 7 Compatible graphics library Currently this feature isn't implemented and there aren't a lot of functions in the high-level category. 2.2 medium-level_library_part This part was called high-level in version 1.1. It's written completely in C. It includes all the graphics primitives like line drawing, area filling and so on. This part uses no direct hardware parameters or interfaces. It uses standardized interfaces to the low-level routines instead. If you need special coding for special hardware or greater speed, you may include this coding in the medium- level part, but use conditional compilation to keep it portable. Though this part is hardware independent, it needs to be recompiled for every new video device. The medium-level part must know some common hardware parameters like the screen resolution. Also there is different coding to be activated for different devices. This ensures the best throughput by using hardware-specific features and also ensures compatibility by also implementing a general, sometimes slower routine. To perform the recompilation successfully the medium-level routines uses the information contained in the low-level header files. So it's very important, that every new device defines it's hardware parameters in it's corresponding header-file. There must also for every device a unique mode-identifier be defined. This identifier allows it the medium-level routines to use special hardware features but remain compatible. 2.3 Low-level_library_part The low-level part is written in C and assembler. This C- coding must use non-standard functions1 to perform its work. A recompilation of this parts with different compilers may be difficult. Only tasks, which couldn't be performed in C are written in assembler. These are most common only the write and read pixel functions. As many coding as possible should be written in C! __________ 0. device is here used as an alias for the low-level device driver functions. 1. like hardware port I/O Page 8 Compatible graphics library The low-level functions are called very often from the medium-level routines, especially the read and write pixel functions. To guarantee a good throughput, these functions should be optimized. It is a good practice, to look very sceptic to these two functions and the whole low-level driver. The low-level routines may implement as many functions as possible, but the user program should only use the standard functions of the low-level part. These are listed in the chapter "User program interface". Using non-standard functions may cause incompatibilities, because some hardware may not be able to perform specific tasks. The list of accessible low-level functions may grew in the future, but it must be granteed that almost every current video device2 is able to perform the task. An example for such tasks may by bytewise addressing of the video memory - but is this identical on all video devices? I think no. So it's a better practice to add new or optimize old high- or medium-level functions. They are much more flexible. 2.4 Stages_of_compatibility The implementation goal of this library was (and is) her great compatibility on a wide range of machines. Though this goal is currently reached nearly 100% in the DOS environment, the design process showed that there are some useful functions which can only be implemented on many, but not all devices. An example for such functions is the video pages system. On systems, where is no direct access to the video memory information, the execution time needed to read a full screen via the read pixel function is much to large to allow a page change. But this function is very useful and can be implemented on many video devices. If you strict exclude such functions, which can't be implemented an all devices, you can't implement a graphics paging system. But if you implement this system only on devices which support them, you destroy the whole compatibility. So I decided to declare a class of "pseudo-portable" functions: These functions are available on almost every video device, but return an error value to the caller.3 This value may say the following: "This function can't be __________ 2. These are not only DOS devices - remember the other popular systems like Apple Mac and Unix systems. 3. using the now implemented error system. Page 9 Compatible graphics library performed by this video device!". It's now the responsibility of the user program to make use of this information and react correctly. Note that there is a great difference between this implementation philosophy and "not to implement" the feature. An error message may also be generated if the feature is available with the current video devices, but there are not enough resources available to use it (not enough memory, e. g.). So the user program has always to look and react at the error codes. Though this is a way of implementing hardware-specific features in this library, I think it should only be used on limited tasks, which should be common to many video devices. There should be as less functions which use such hardware- specific features as possible! 3. Installation_of_the_library This section covers the whole installation process, which must performed by you in order to get the library working. To ease this task, only the pure installation process is described, not the way to make the library suit your meets. This task is covered in the section "Modifying the library", where useful information about extended configuration parameters can be found. But be warned: this section was intended for use by those who want to part the library to a new environment or make serious changes. The information presented there is very technical. 3.1 Bringing_up_the_library The following files are guaranteed to be on the distribution disc. Page 10 Compatible graphics library File name file description graf.s This documentation file in nroff source code format. graf.txt This documentation file as pure ASCII text. readme.doc Contains latest information, which is not included in this document. grafturt.c First part of the high-level library part, contains the turtle graphics system. graf.c First part of the medium-level library part. graftext.c Second part of the medium-level library part. herc.c First part of the hercules low-level driver herca.asm Second part of the hercules low-level driver. ega.c First part of the ega low-level driver. egaa.asm Second part of the ega low-level driver. bios.c Standard BIOS low-level driver. xxhr.c Driver for the Elsa PC XXHR graphics card. btrigtab.c Program to build trigonometric tables. graphics.h High-level header file. herc.h Low-level hercules device header file. ega.h Low-level ega device header file. bios.h Low-level BIOS header file. xxhr.h Low-level xxhr header file. dos.mac Macro file for the assembly language modules. allglob.h Header file for programs, which want to use the world coordinate system only. basnames.h Basic equivalence macros. For users who like basic function names. stdfont.h Standardfont for use by graftext.c. trigtab.h Precomputed trigonometric tables. Should be rebuild on the target machine using btrigtab.c. blddsk.bat MS-DOS library disk build routine. This file list may be extended in the future. The distribution disk shipped to you may contain additional object (.obj) files. Especially the assembly language files will come per-assembled, because not everybody will own an assembler. But the availability of object files will be depending on the free space on the distribution disk. I try to copy all object files for every supported compiler and memory model to the distribution disk. But these files need a lot of space, so it can't be guaranteed that these files will be on the disk. Page 11 Compatible graphics library Look at the file "readme.doc" for the current file organization on the distribution disk. To install, you have first to copy all the files you need from the distribution disk to either a new floppy or your working directory on your hard-disk. You need at least the high- and medium-level source code and header files and one complete (C and ASM source and header file) low-level driver. If the objects for your compiler and memory model are on the distribution disk, the installation is done and you can begin using the library. If not, you have to compile the source files with your compiler. If your compiler is not currently supported by the library, switch to section "Modifying the library", where some useful information for the port to a new compiler can be found. Also switch to this section, if you want to make some configuration changes to the library. To compile the delivered version of the library, first choose which graphics device do you want to use. After that, copy the corresponding low-level header to the generic low-level header file "graf.h". After that, simply compile the high- and medium-level library files as listed above. Than compile the low-level file and assemble the assembly language part of the low-level driver, if given. Note that you have to modify the file "dos.mac" to your requirements to perform the assembly successful. See the following subsection "Configuring dos.mac" for information about this task. You should combine the resulting object files to a single library, which simplifies the link-procedure. If you need multiple memory model support, perform the above steps for each memory model you selected to use. After doing the compilations, you may have to modify your link-batchfiles. For example, the Lattice C compiler comes with 8 batchfiles named LINKS, LINKD, LINKP, LINKL, LINKMS, LINKMD, LINKMP, and LINKML. These batchfiles don't allow you to specify your own librarys. You have to modify them like in the following example: LINKS contains: link /lc/s/c +%1 %2,%1,%1/map,/lc/s/lc You modify this to: link /lc/s/c +%1 %2,%1,%1/map,/lc/s/lc+"name of your graphic library" Note: Slash (/) were used as path delimiter! After you have done this, you are ready to use the library. Page 12 Compatible graphics library If you use the a compiler with cc-like utility (integrated compile/link), just name your library on the command line. It will be automatically included in the link procedure. 3.2 Configuring_dos.mac The assembly routines need to know about the environment, in which they have to execute. They have to know about the calling compiler and the memory model used. This environmental data is kept in file dos.mac. In order to successful reassemble the assembly language files, you have to modify file "dos.mac" so that it represents the execution environment you decided to use. In order to ease this job, there are predefined tags in file "dos.mac". The following display list is extracted from dos.mac and lists these tags and gives a brief description. ; ; Define Memory-model to use ; -------------------------- ; Equate the memory model to use to 1, all others to 0. ; S_MODEL equ 1 D_MODEL equ 0 P_MODEL equ 0 L_MODEL equ 0 ; ; Define C-compiler to use ; ------------------------ ; Equate the label, that describes your C-compiler to his current ; version (major version number * 10 + 1st digit of minor version ; number). All other labels must be equated to 0. ; LC equ 0 ; Lattice C DLC equ 22 ; Datalight C V. 2.2x MSC equ 0 ; Microsoft C NOT TESTED TC equ 0 : Borland Turbo C As listed above, you have to equate the memory model to use to 1, all others to 0. If your compiler supports different memory models, select one of the above according to the following table: Model Code Data S 64K 64K P unlmtd 64K D 64K unlmtd L unlmtd unlmtd The equate of your compiler to his version number makes Page 13 Compatible graphics library calling-sequence changes4 transparent to the graphics library. Note that these configuration tags will be extensive error- checked and all detected errors will be reported during assembly. Nevertheless, you should be very carefully, when modifying these parameters, because not all errors can be detected (e. g. wrong memory model chosed). Be aware of the fact, that the MSC macros aren't tested yet. I think the work, but I've currently no access to MSC. So expect some trouble if you decide to use the MSC driver. 4. User_program_interface 4.1 Header_files The user program interface is defined in the various header (.h) files. There are two classes of header files: First ONE (and only one) header file defining the high- and medium-level functions and constants. This header file is named "graphics.h". Second there are many header files defining the low-level functions and constants. These low-level header files may be used in two different ways: First you may include the device dependent header files by name, e. g. "hercgraf.h" for the Hercules graphics card. This way has the disadvantage of missing hardware independency of the user code. If you want to move to a different video device, you have first to change the header file names in all of your sources. The second way to use the header files is to include a generic filename, e. g. "graf.h". You may copy than the correct header file (e. g. "hercgraf.h") to this generic file. If you want to switch another video device, just copy the new header file to the generic file. There is nothing more to do, no code must be changed! I think this second method is much better and should always be used. The medium- and high-level routines use this method too5. To aid you in using this "good"6 method, the __________ 4. that may occur during compiler development 5. See "Modifying the library" Page 14 Compatible graphics library medium-level header file does a #include "graf.h". If you don't want this, please do a #define NOLLHINC 7 before #including the high level header file. 4.2 Available_function_calls The following is a brief description of the available function calls. It is guaranteed that these functions will work in every implementation. Each function is listed with her name, parameters and a description. These information can also be found in the sources, from where it is extracted. If you need more information about a particular function, look at the sources. There can be much more information found than in this document. But beware of the fact, that the internal algorithms are subject to change without notice! ____________________________________________________________ 6. hope you think so too 7. NO Low-Level Header file INClude Page 15 Compatible graphics library 4.2.1 Box_function name box class medium-level synopsis box(x1, y1, x2, y2, color); int x1, y1; upper left corner int x2, y2; lower right corner int color; border color description This function draws a border of "color" covering the given box. The box is specified through the upper left (x1, y1) and to lower right (x2, y2) corner. The box itself isn't modified (e. g. must be cleared explicitly). Page 16 Compatible graphics library 4.2.2 circle_function name circle class medium-level synopsis circle(x, y, radius, color, aspect) int x, y; center coordinate int radius; circle radius int color; circle color float aspect; aspect ratio description This function draws a circle according to the given parameters. Note that this function is only capable of drawing a full circle. see also ellipsis Page 17 Compatible graphics library 4.2.3 convxco_function name convxco class medium-level synopsis locx = convxco(x) float x x coordinate to convert int locx hardware x coordinate description This function converts a global coordinate to a local, hardware dependent coordinate. Its return value may be directly passed to other functions. see also convyco, convxdis, convydis Page 18 Compatible graphics library 4.2.4 convxdis_function name convxdis class medium-level synopsis locxdist = convxdis(xdis) double xdis distance to convert int locxdist hardware distance description This function converts a global x distance to a local, hardware dependent x distance. Its return value may be directly passed to other functions. see convxco, convyco, convydis Page 19 Compatible graphics library 4.2.5 convyco_function name convyco class medium-level synopsis locy = convyco(y) float y y coordinate to convert int locy hardware y coordinate description This function converts a global coordinate to a local, hardware dependent coordinate. Its return value may be directly passed to other functions. see also convxco, convxdis, convydis 4.2.6 convydis_function name convydis class medium-level synopsis locydist = convydis(ydis) double ydis distance to convert int locydist hardware distance description This function converts a global y distance to a local, hardware dependent y distance. Its return value may be directly passed to other functions. see convxco, convyco, convxdis Page 20 Compatible graphics library 4.2.7 ellipsis_function name ellipsis class medium-level synopsis ellipsis(x, y, rx, ry, ws, we, color) int x, y center coordinate int rx x - 'radius' int ry y - 'radius' int ws begin angle 0..360 int we end angle 0..360 int color line color description This function draws any sort of ellipsis. It is often called circle, but I think this name should better be reserved for a function, which only draws a FULL circle (see above). This function may not only draw a circle or any possible ellipsis, it is also capable of drawing only parts of. them. This feature is often used in pie-charts. Because of its great flexibility, this function is much slower than circle. If you only want a full circle (or ellipsis) you should call circle. see also circle, fellipsis Page 21 Compatible graphics library 4.2.8 fellipsis_function name fellipsis class medium-level synopsis fellipsis(x, y, rx, ry, ws, we, color) int x, y center coordinate int rx x - 'radius' int ry y - 'radius' int ws begin angle 0..360 int we end angle 0..360 int color line color description This function is much like ellipsis(), but it's faster because it uses only full angles to draw the ellipsis. Note that this function produces good results only for small radius-values. also ellipsis, circle Page 22 Compatible graphics library 4.2.9 fillbox_function name fillbox class medium-level synopsis fillbox(x1, y1, x2, y2, color); int x1, y1; upper left corner int x2, y2; lower right corner int color; fill color description This function fills a given box with the specified color. The box is specified through the upper left (x1, y1) and the lower right (x2, y2) corner. This function is the counterpart to box, which draws the border. Page 23 Compatible graphics library 4.2.10 getpixel_function name getpixel class low-level synopsis color = getpixel(x, y); int x, y; coordinate of the pixel int color; returned color of that pixel description This function reads ("gets") the color of a specified pixel. Page 24 Compatible graphics library 4.2.11 grperror_-_print_last_error name grperror class medium-level synopsis grperror(fil); FILE *fil; file to put error-message in (or NULL if to put on current display). char *msg; error-message header text (like perror). description This function prints the last detected error that occurred in the graphics library. It has the ability to write to a user text file or to the current graphics screen. Writing to a file may be useful for not destroying your graphics display. You chose between this both modes by your file pointer: if it is NULL, the function writes to the display, otherwise it uses your file pointer to write to that file. No write errors are reported. The function writes first the user-specified message, than the internal error-message. Page 25 Compatible graphics library 4.2.12 gt_backw_function name gt_backw class high-level synopsis gt_backw(count) int count; count to move backward description This function is the opposite to function gt_forwd. It moves the turtle the specified position in backward direction. see gt_forwd Page 26 Compatible graphics library 4.2.13 gt_dir_function name gt_dir class high-level synopsis gt_dir(degrees); int degrees; new turtle direction in degrees. description This function sets the absolute turtle direction in degrees for further moves. If the value contained in "degrees" is invalid, it will be converted into the range 0..359. Negative degrees will be correctly converted to their positive counterpart. see gt_tleft, gt_trgth Page 27 Compatible graphics library 4.2.14 gt_forwd_function name gt_forwd class high-level synopsis gt_forwd(count) int count; count to move forward description This function moves the turtle forward the specified count of 'logical' pixel (or backward, if negative). see gt_backw Page 28 Compatible graphics library 4.2.15 gt_hide_function name gt_hide class high-level synopsis gt_hide(); description The turtle isn't shown after drawing operations if this function is called. Page 29 Compatible graphics library 4.2.16 gt_home_function name gt_home class high-level synopsis gt_home(); description This function sets the turtle to the home position. After this function call, the turtle will be located at (0,0) (middle of screen) and points in upward direction. Page 30 Compatible graphics library 4.2.17 gt_init_function name gt_init class high-level synopsis gt_init(); description This function initializes the turtle-graphics package. It clears the graphics screen and initializes the global to local coordinate system with the default turtle window size. All turtle parameters are reset to their defaults, which are as follows: - turtle position (0,0) - turtle direction 0 - turtle visible no - turtle delay none - turtle window -400,200,400,-200 - turtle pen up no - turtle pen color 1 Note: This function MUST be called before any other turtle graphics function. If it's not called, the other function may crash. This function MAY be called at any time to reset the turtle graphics system. Page 31 Compatible graphics library 4.2.18 gt_pcolr_function name gt_pcolr class high-level synopsis gt_pcolr(color); color; new pen color description This function sets the turtle pen color. All further drawing will use the specified color. Note: The pen status is not modified, so if the pen is lift up, no drawing will take place. Page 32 Compatible graphics library 4.2.19 gt_pendn_function name gt_pendn class high-level synopsis gt_pendn(); description This function lifts the turtle pen down, so that a line will be drawn by further movements. The pen may be lift up by function gt_penup. note It is not reported as error, if the function is called while the turtle pen is already lift down. see gt_penup Page 33 Compatible graphics library 4.2.20 gt_penup_function name gt_penup class high-level synopsis gt_penup(); description This function lifts the turtle pen up, so that no line will be drawn by further movements. The pen may be lift down by function gt_pendn. note It is not reported as error, if the function is called while the turtle pen is already lift up. see gt_pendn Page 34 Compatible graphics library 4.2.21 gt_setco_function name gt_setco class high-level synopsis gt_setco(x, y); int x,y; new turtle coordinates. description This function sets the turtle to the given position. The position is a turtle graphics coordinate. No line is draw while repositioning the turtle. Page 35 Compatible graphics library 4.2.22 gt_show_function name gt_show class high-level synopsis gt_show(); description The turtle is shown after each drawing operation if this function is called. Page 36 Compatible graphics library 4.2.23 gt_tleft_function name gt_tleft class high-level synopsis gt_tleft(degrees); int degrees; turtle rotate count in degrees description This function rotates the turtle in left direction, using the rotate count specified in degrees. Negative counts mean rotate to right position. see gt_trght, gt_dir Page 37 Compatible graphics library 4.2.24 gt_trght_function name gt_trght class high-level synopsis gt_tleft(degrees); int degrees; turtle rotate count in degrees description This function rotates the turtle in right direction, using the rotate count specified in degrees. Negative counts mean rotate to left position. see gt_dir, gt_tleft Page 38 Compatible graphics library 4.2.25 gt_usrmv_function name gt_usrmv class high-level synopsis gt_usrmv(speedtab); int *speedtab; speed table for moves. description This function allows it the program to give the user control over turtle movement. The function accepts single keystroke commands. The commands are not echoed. The caller may supply a table of speed values for each supported speed (0 .. 9). This table consists of 10 int-type entries, which holds the movement entity in the selected speed. If the user wishes to use the default speed table, he must supply a NULL pointer. Commands available: 0 .. 9 : select turtle speed. n : turtle direction north e : turtle direction east w : turtle direction west s : turtle direction south h : home turtle b : move turtle backward f : move turtle forward l : turn turtle left 1 degree L : turn turtle left 5 degrees r : turn turtle right 1 degree R : turn turtle right 5 degrees g : go, change no direction q : quit this function Note: The turtle system must be initialized before calling this function. The current state of the turtle system is not altered before execution, so all parameters are as set by you. Page 39 Compatible graphics library 4.2.26 gtgetdir_function name gtgetdir class high-level synopsis degrees = gtgetdir(); int degrees; current turtle direction in degrees. description This function returns the current turtle position in degrees. The returned value will be in range 0 .. 359. Page 40 Compatible graphics library 4.2.27 Line_function name line class medium-level synopsis line(x1, y1, x2, y2, color); int x1, y1; starting coordinate int x2, y2; ending coordinate int color; line color description This function draws a line of "color" between the starting (x1, y1) and ending (x2, y2) coordinate. Page 41 Compatible graphics library 4.2.28 paint_function name paint class medium-level synopsis paint(x, y, paintclr, border) int x, y; coordinate of a point within the area int paintclr; the color used to paint int border; is the color of the border defining the area description This function paints an area. The area is defined by a border of a specified color ("border") and the coordinate of one pixel within the area (x, y). The color used to paint is given in "paintclr". This function uses several subroutines and a recursive algorithm! It's only the "initializer", the main work is performed by the other Routines. Page 42 Compatible graphics library 4.2.29 polyline_function_-_draw_complex_lines This function may be used to draw charts or complex geometric figures. name polyline class medium-level synopsis ret = polyline(color, coords, ...) int ret; 0 on success, -1 otherwise. int color color of the line int coords coordinate list (x, y), ends with -1, -1 description This function draws a polyline. That means a line, which is made of multiple coordinates. You supply as many coordinates as you need to describe the line in an integer array. They must be in (x,y) order. The end of the coordinate list is indicated by the coordinate pair (-1,-1). The function starts now at the first coordinate and draws a line from this point to the second coordinate. From there it draws a line to the third coordinate and so on, until the end of coordinate list is reached. If the coordinate list is in- valid, the function returns a true (-1) result, otherwise it returns false (0). In case of an error return the graphics error variable may be examined. The line is drawn in color "color". Page 43 Compatible graphics library 4.2.30 print_screen_function_-_hardcopy This function allows a program-controlled hardcopy of the current graphics page. Warning: currently only available for the hercules graphics card! name prtgraf class medium-level synopsis ret = prtgraf(); int ret; 0 if successful, -1 otherwise. description This function prints the entire graphics- screen on a dot-matrix printer. The function was developed using a NEC P6 printer, but should run with little alteration on every EPSON compatible printer. The function return 0 if successful, -1 if not. In case of an error return the error system holds an extended or code. Page 44 Compatible graphics library 4.2.31 putmsg_-_complex_text_output_function name putmsg class medium-level synopsis putmsg(x, y, foreg, backg, string, font, mode); int x, y; starting coordinate (upper left corner) int foreg; foreground color int backg; background color char *string; string to draw int font; font-number to use int mode; output mode (font modifier) description This function draws the string pointed to by "string" on the graphics screen. The string must be -terminated. Drawing begins at x,y, which is the upper left corner of the first character in the string. The characters are painted in color foreg, the character- background is painted in color backg. The font to use must be specified in font. Currently only STDFONT is supported. Field mode contains the string output mode, which is a font modifier. This field may be used to select italics or other output modes. Currently only OM_NORM, OM_ITAL and OM_RITAL are supported. Page 45 Compatible graphics library 4.2.32 setgloco_function name setgloco class medium-level synopsis setgloco(x_beg, y_beg, x_end, y_end) float x_beg, y_beg minimum coordinates values float x_end, y_end maximum coordinates values description This function initializes the global/local coordinate system. This system allows you to address your pixels based on a global coordinate system. This system is independent from the hardware coordinate system. Global coordinates may be converted to local coordinates, which are to be used to address the hardware. So your application hasn't to look at the present video hardware but use always a hardware independent own coordinate system. In addition you may use floats, not only integers as coordinates. This is a great advantage in numerical applications. warning This function initializes the system, so any call to the convert routines will return garbage, until this function is called! Page 46 Compatible graphics library 4.2.33 setpixel_function name setpixel class low-level, old call, compatibility class synopsis setpixel(x, y, color); int x, y; coordinate of the pixel int color; pixel-color description This function sets a pixel of color "color" at the specified coordinate. warning This function is superseded by function wrtpixel. It's included mainly for compatibility reasons. It does not not support the graphics write mode. Do not use this function call, if you do not absolutely need backward compatibility to version 1.1 of the library! Page 47 Compatible graphics library 4.2.34 setwm_function name setwm class medium-level synopsis setwm(mode); WRITEMOD mode; new write mode description This function sets the library write mode. All write operations are performed in respect to the current write mode. For a list of currently supported write modes see the definition of WRITEMOD in graphics.h! Page 48 Compatible graphics library 4.2.35 wrtpixel_function name wrtpixel class medium-level synopsis wrtpixel(x, y, color); int x, y; pixel coordinate int color; pixel color description This function sets a pixel in the given color at the specified coordinate. The pixel is set in respect to the current write mode. 4.3 Linking_using_object_files_or_librarys There are two ways to link the graphics routines into your program. The first were described above: You may use the librarys build during the installation process. Then you have only to alter your link-batchfiles, the rest is automatic. This is normally the best method. But this method has the disadvantage of including the librarys in every of your link-sessions. This needs time (especially on floppy-based systems). So, if you only need the libraries in a few programs, you may think that this way isn't the right. Then you may use the second method: You may not only specify the libraries, you also may specify the routines as stand- alone objects. So link only the object files in your program. You have to name the files each link-session (or construct a short batch-file). Please remember, that there are low, medium and high level routines. You have to include all of them in the link-process. Here is a sample link-call using the std. Lattice link-files and the hercules low-level driver: LINKMS your-program +graf+herc+herca Note that you do not always have to include three object files. The standard BIOS driver, for example, has only one low-level object file, because the complete low-level handling can be done in C. However, I think there will be mostly two low-level drivers. You may specify the object-file names at any position, the above given is only one possible specification. You must only link your main program first, because this is the name Lattice uses for the .EXE file. Caution: The general medium-level driver must be compiled separately for each low-level device (as stated above). So you have to use different medium-level object files. Using wrong medium-level drivers may cause link errors and/or Page 49 Compatible graphics library program crashes! 5. Customization_of_the_library This section contains information about how to customize the library to your specific needs. In general the library is unmodified usable, though the this version may not the best for your needs. In order to make the library more useful, there is a facility to change the behaviour of the library with only a few configuration parameters. This parameters are contained in file "graphics.h". By setting this parameters to new values, you can create a version that's more special to your needs, without completely modifying the library. This facility should allow you to configure many library features to your needs, although it is not as powerful as really modifying library source code. But I think it will be powerful enough for most purposes. The configuration parameters are explained in the top part of "graphics.h". For a detailed description of configuration changes see this file. Note: after changing configuration parameters, the whole library must be recompiled! 6. Modifying_the_library If the above described way of customizing the library is not powerful enough for your needs, or if you plan to port the library to a new environment, the information needed therefore is contained in this chapter. But be aware of the fact, that modifying the library requires working knowledge of the C programming language and porting the library requires good knowledge of the target machine. If you do not fulfill the above requirements, ask someone else for help or you can become frustrated! The following sections contain information about the internal implementation and general philosophy of this library. If you modify the library, please don't violate the basic concepts, because such violations will cause Page 50 Compatible graphics library problems with newer releases. It also would be fine, if you not only extend or port the library, but also update this manual. If you use new or significant faster algorithms, please notify the author, so he can make these changes common to all users and include them in further developments and enhancements. In either case, please inform the author of bugs. The will be fixed as fast as possible (if you developed a fix, please send it too!). For a general overview see sections "Library design". You should read this section before continuing here. 6.1 Basic_rules This section points out the basic rules for modifying the library. NEVER violate these rules, otherwise you can not be sure to move to new levels of the library without problems. Coding, which violates these rules, isn't accepted nor enhanced by the author. I think these rules are so basic software-engeneering rules that I can point out them for short. 1. Never use compiler-specific features. This is the dead for portability! 2. Never use undocumented routines. They may be removed or modifyed without notice. 3. Use only the documented interfaces. Static variables only contain useful information, if such is guaranteed! 4. Never change the documented interface of a function. You would destroy portability. If you add new functionality to a procedure, which requires a new parameter, use a different function call name. You may internally call the old function to avoid duplicate coding. 5. Never introduce a routine which is hardware-specific. Use at least a pseudo-hardware-independent function, as stated above. But do use such functions only if absolutely necessary and it is supported by most video-devices (I think at least 75%). Remember, that __________ 7. like the high-, medium and low-level driver concept 7. or use sub-subroutines Page 51 Compatible graphics library one goal of the library was the portability on a wide range of machines. So there have to be as less as possible hardware-dependent functions. You may use hardware-dependent functions internal, but they should not be documented as legal functions. 6. You should try to implement new features in the hardware-independent, high- or medium-level part of the library. So porting this function to a new environment isn't painful. 7. Never implement hardware-dependent functions in the high- or medium-level part. If you introduce a hardware-dependent function, which is common to many video devices (and may be emulated by the others), put this in the low-level parts. This makes implementation of the library more visible. In addition, ones who want to port the library to new devices can be sure, that they must not modify the high- and medium-level part. 8. You may modify parts of the medium-level routines to call some hardware-specific routines if, and only if, there is also a implementation of the same thing using the standard read/write pixel interface. You have to use conditional compilation to activate your coding for a special video-device. Such an implementation makes sense, if you can reduce the runtime significantly. An example for this is the EGA device. 9. Always document a new function or function enhancement. Use the standard function header in your source to document a new function. If you port the library to a new operating system, compiler or video device, please complete the information in the header page of this document. __________ 7. which are then implemented in the low-level part 7. See the library sources for an example. Page 52 Compatible graphics library 6.2 Library_Modes The graphics header-files are included in both user and library programs. However, these files have to do different jobs in each case. In order to simplify maintenance, the header files contain information to do all jobs correctly. The current job is selected via the library mode preprocessor variable LIB_MODE. This variable has to be defined before #including the graphics header files. This variable may hold different values, thus selecting different coding in the header-files. Currently modes 0, 1 and 2 are defined, but new can be added on demand. mode 0 is the user mode. It is also set if LIB_MODE isn't defined. In mode 0 all library internal features are disabled. mode 1 is the primary library mode. All internal features are enabled, but library variables are declared to be external. mode 2 is much like mode 1, except that the library variables will be allocated. So this mode can only be set in one module. This module is called the master module, because it allocates the whole library external data space. 6.3 Function_sets The medium-level library part contains two function sets. The function set are almost identical in the calling sequence. This two sets are introduced by the write mode system. Generally drawing is done in normal write mode, what means directly with the user-specified color. But if it's done in one of the other modes, the color must first selected according to the user-specified color and the previous contents of the display buffer. Thus the second approach is much more time consuming, even because some optimizations can't be applied to write modes other than normal. So most functions have two forms: one very fast, strictly optimized normal write mode version, and one more general but also slower all write modes function. This design is completely invisible to the user program, because the user program always calls the fast alternative and this function switches to its slower pendant if needed. Note that this approach is unique to the medium-level library part. If you plan to extend this part you have to Page 53 Compatible graphics library know, that there is a function which supports write-mode applications. It's function sel_color(), which automatically selects the drawing color for the pixel it is called for. Note that this function will be included in all further releases and so it's save to use it. It's not documented because it's invisible to user programs. For the calling sequence look at the source code function header in file graf.c. 6.4 Modifying_High-Level_Parts The high-level library part has to be completely hardware independent. So no calls to hardware specific routines or other hardware specific features can be included. Do only use the documented interfaces of the medium- and low-level library parts. Always remember, that the lower level parts will be dynamically loadable in the future. I think that the high-level library part will be the least part modified. I also think such modifications make only sense in case of bug fixes and functionality enhancements. 6.5 Modifying_medium-level_parts The medium-level library parts should be hardware- INdependent. Though, you may include some special hardware-calls if you use conditional compilation. This way may be chosen, if the performance may grew rapidly. However, if you use this way, implement the hardware- dependent parts as calls to low-level routines performing the job. Also there must be always a routine implemented, which only uses the basic low-level routines for reading and writing a pixel. This guarantees portability. All #define's, which are common to almost every video-device should be done in the medium-level header file (same as the high-level header file). There should also all documented functions be prototyped. Please use conditional compilation, if you use newer language features like void or enum, so these constructs can be easily commented out. Use different names for each new feature, because some compiler implement part of this new features. They should be used if possible. Note that the word USE_VOID e. g. is currently in use by the library to implement the void keyword. Whatever you do, keep in mind that the medium-level part should be as portable and hardware-independent as possible. __________ 7. #if(?) ... #else ... #endif Page 54 Compatible graphics library But you should also remember, that the medium-level part must be recompiled for each low-level driver... 6.6 Modifying_low-level_parts You may modify everything except the few documented and guaranteed function-interfaces. But you should try to implement as much coding as possible in C, because you may use parts of existing low-level drivers or others may use your drivers to implement another video-device. Also a port of existing drivers to another operating system may be simpler, if the driver is written nearly complete in C. You should use low-level routines only if it's impossible to do the same with medium-level routines (or to get a much better performance). Please let your low level-routine communicate with the medium-level routine only by using strictly defined interfaces. Do not introduce a low-level routine for common usage, if it can't be implemented on almost every video-device! 6.7 Modifying_header_files Header files play a very important part in the library design - so do not forget them. Every new high- or medium- level routine or definition should be added to the ONE AND ONLY medium-level header file "graphics.h". Do not add a second or third high/medium-level Header file! Put a device-id in every low-level header file (HERCGRAF is an example). So the medium-level routine knows which is the current low-level driver and may activate different coding. It may also be of interest for the user-program to know which video-device is active. 7. Development_environment It may be interested for you to here something about my development environment. The library were implemented on 2 IBM-AT's. One is equipped with a hercules-compatible monochrome graphics card, one with the Quad-EGA and a monochrome display. So there could be no development done for color-graphics, but I think the EGA-routines will run using color-graphics, too. One AT is equipped with 2.5Mb, one with 512Kb memory, both without 80287. Both are running under PC_DOS 3.1 (German version), one under XENIX, and one under Mikroport's Unix System V. There were some resident programs loaded. The software environment consist of the sh and related utilities by Allen Holub, the Lattice, Datalight, Datalight Page 55 Compatible graphics library optimizing and Borland's Turbo C compiler and Microsoft MASM 4.0 and related products. The files were edited using the Turbo Pascal editor. This document was edited under UNIX, using vi, nroff and the mm macro package. My (new) own AT is the one equipped with 2.5Mb, no 80287 and the Quad-EGA. I currently own the sh and utilities, the Datalight, Datalight optimizing and Borland's Turbo C compiler, the Blaise runoff formatter and the standard IBM PC linker. I also own the PC/vi editor, which is really great, and Mr. Holub's nr text formatter, which is much better than the Runoff formatter (and much less expensive!). The system is also equipped with Hersey Mikro Consultings Fansi-Console, which greatly speeds up consol writing, but unfortunately needs a lot of memory (50 Kb from small 640 Kb DOS memory). And I'm running Microport's UNIX System V-AT since one month. Now think about new features, which can be developed with this environment... 8. Future_enhancements This chapter list the current and planed developments, which will be made available in the future. In addition to these points I want to get some feedback from you, resulting in a better and better library. This feedback may be in form of new ideas, algorithms and, of course, critic. I really love to hear your comments, because I myself cover only a little span of potential applications, so my library will always be restricted, until you send my new ideas. But enough of the feedback, here are the facts about future enhancements: - First of all, the high-level library part will be greatly enhanced. I hope I can implement many useful high-level functions in the near future. This will include a metafile system and related plotter drivers (have you seen the new plotter entry in the heading page?). - text output will be advanced. The current text-output function only supports a limited functionality. This functionality will be __________ 7. , which are really great!!!! Page 56 Compatible graphics library greatly enhanced. More style-modifiers and loadable character sets will be implemented. Also a font-editor may come with the next release. - virtual graphics pages will be implemented These implementation of virtual pages will base on a hardware-independent algorithm, so that multiple display pages will also be available on devices which not directly support them. In addition, because graphics need a lot of memory, which is not available at some systems, the library will implement an algorithm, which is able to use mass-storage for inactive pages (virtual memory management). - I try to port the library to the UNIX operating system I'm not sure, that these port will be successful in the end. I'm not very similar with the UNIX operating system, nor with graphics programming using UNIX and, of course, graphics terminals. My first attempt to implement the library was not successful, but I learned that an operating system like UNIX is very, very secure (so secure that my I/O-instructions don't work). Don't misunderstand my: I really love the way UNIX goes, but I don't know currently how to implement the library. But I also think that the port will be possible now, where I can use my own Unix. Help! If someone has some information about this job, please write me. I would happily receive each piece of information. 9. Final_observations At this point, thanks to all "heros", which read this whole document. I know, my English is very bad, so I hope you excuse all the little (or should I better say big!?) errors in spelling and grammar. I hope my English will grew better in the future, so the documents will grew better, too. In addition, I want to thank all people which will contact my (I hope there will be some). I also want to thank the C User's Group for distributing the library and this document. Page 57 CONTENTS 1. Introduction........................................ 3 1.1 Design history and background.................. 3 1.2 Current features............................... 3 1.3 new features and enhancements of version 2.1............................................ 4 1.4 Release compatibility.......................... 7 2. Library design...................................... 7 2.1 High-level library part........................ 7 2.2 medium-level library part...................... 8 2.3 Low-level library part......................... 8 2.4 Stages of compatibility........................ 9 3. Installation of the library......................... 10 3.1 Bringing up the library........................ 10 3.2 Configuring dos.mac............................ 13 4. User program interface.............................. 14 4.1 Header files................................... 14 4.2 Available function calls....................... 15 4.3 Linking using object files or librarys......... 49 5. Customization of the library........................ 50 6. Modifying the library............................... 50 6.1 Basic rules.................................... 51 6.2 Library Modes.................................. 53 6.3 Function sets.................................. 53 6.4 Modifying High-Level Parts..................... 54 6.5 Modifying medium-level parts................... 54 6.6 Modifying low-level parts...................... 55 6.7 Modifying header files......................... 55 7. Development environment............................. 55 8. Future enhancements................................. 56 9. Final observations.................................. 57 - i -