============================================================================= Graphics Class Library for Linux ============================================================================= Introduction ------------ This is my Graphics Class Library for Linux. It's built on Tommy Frandsen's VGAlib, but includes additional neat features which are: (a) The library is set up in a multi-layered fashion, where one module is based on a previous module. This allows the programmer to choose which layer to use and allows the construction of new, more specialized, layers. (b) The library contains "class" functions, which may be used in C++ programs. The responsibility for some of the administrative tasks of the graphics interface is thus taken from the hands of the programmer and is placed into the (automatically called) constructors and destructors. (c) The library contains a class for text display. This is a completely new feature, not present in VGAlib. The text is displayed according to a font which is 'compiled-in'; this font is the same 8x8 pixel font used by DOS in graphics modes. (d) The ability to draw lines and pixels, also possible with VGAlib, is enhanced by the ability to define 'windows', where displayed lines are 'clipped' so that no drawing takes place outside the windows. This library also lacks features, such as the display of circles or the filling of areas. I did not implement these features because I do not use them; this library was built to enable a port of a scientific data plotting program under DOS program to Linux and not for the purpose of creating an 'all-in' graphics library. New features may be added 'ad lib' --- when they are needed. To recapitulate the 'handy' features vs. the 'not-handy' features of VGAlib, and therefore of the Graphics library: This software is extremely simple to use if you want to create a graphics display under Linux. However, the resulting software can only be run on the Linux console, since the software assumes that it can directly access the VGA card. The same software therefore cannot be run if you, e.g., telnet to a Linux box from an other machine. Furthermore, the software using VGAlib can only be run as 'root'; otherwise, VGAlib fails to obtain the necessary permissions. Requests for features, bug reports etc. --------------------------------------- Please mail me if (no.. make that when) you enconter bugs in this software. Also, mail me if you have comments about the documentation or requests for new features. I can be reached at: internet karel@icce.rug.nl, K.Kubat@icce.rug.nl phone (+31) 50 63 36 47 mail Karel Kubat, State Univ. of Groningen, ICCE Westerhaven 16, Groningen Netherlands Description of the Graphics Library ----------------------------------- The Graphics library consists of four classes, which are: (a) class Graph: This is the basic class of the library. It serves no other task than to interface to VGAlib. This library was implemented to realize a transparent and easy to maintain 'tunnel' to the actual software which manipulates the graphics screen. This class also allows for the porting of the Graphics library to another platform or another graphics system. (b) Class Gwin: This class defines windows for the display of pixels or lines. It is derived from the class Graph. Features like, clipping, clearing a window, foreground/background colors, etc. are located here. (c) Class Grecwin: This class is derived from Gwin, but permits the 'recording' of the drawing of lines or dots. The recording may be 'replayed' to re-display the window. The replay feature is handy when a number of lines or dots should be cleared -- they only need to be redisplayed using the background color. (d) Class Gbittext: This class defines an 8x8 pixels bit-oriented font and contains functions to show text in this font. Furthermore, text windows which are part of the screen may be defined here. Further documentation about these classes is located in the directory doc in the files graph.2, gwin.2, grecwin.2 and gbittext.2. These files contain, e.g., a short description of each public function of the classes. Installation ------------ The Graphics library comes as a zip 'graph.xxx.zip', where xxx defines the version number. Alternatively, you may encounter a .tar.Z or .tar.z file. These files unpack by means of unzip, gunzip and/or tar into the *current* directory. I've tried to make the installation process as easy as possible; but suggestions for improvement are always welcome. To install the Graphics library please follow these steps: (a) Make a source directory. A suggested name is /usr/src/graph. Then, cd to this directory. (b) Unpack the archive which contains the sources into this directory. A number of subdirectories should be created at this point; e.g., doc, graph, gwin, gbittext, test. (c) Edit the main Makefile in the top level directory to suit your purposes. Make sure to define the directories in this file to your likings. The directories, defined as macros at the top of the file, are used in "make install". (d) Edit the Makefiles in each of the directories containing sources; these directories are all subdirectories except doc. You can change the CFLAGS definitions in these Makefiles from -g to -O. The compiler flag -g causes gcc to include debugging information into the object files and executables; this is the default for me. The compiler flag -O causes gcc to optimize and not to include debugging information. (e) Furthermore, make sure that the symbol VGA_O, defined in the top-level Makefile, points to the file "vga.o" which contains Tommy Frandsen's VGAlib functions. This object file is included in the library "libgraph.a" which is created in the making process. (f) At the top level directory, type "make compile". All source files which are needed for the Graphics library should then be compiled and placed into libgraph.a. (g) Next, do a "make install". This installs libgraph.a into the library directory defined in the top level Makefile and installs all header files (one for each class) into the include directory defined in the top level Makefile. Note that you can always do a "make uninstall" to remove the library and header files from your system directories. It should be obvious that you need to be root to make an (un)install. (h) To remove the object files, which are no longer necessary, do a "make clean". (i) If you'd like to see some demo's, cd to the directory "test" and do a "make". A number of programs will be created, which I wrote for testing purposes. The first few of these programs are fairly simple, since these were my first tests. You may wish to examine the source files for these programs to see how the Graphics library is used. Note that the "make install" is not necessary for the making of the test programs; only the "make compile" is necessary. You can therefore first compile the Graphics library and check it out to see if you like it; and then install it. (j) A "make clean" at the top level directory removes the object files and test programs. Also, the library itself is removed; if you like to keep it, be sure to "make install" prior to "make clean". (k) An other options for the making process is "make doc2man". This copies the crude documentation from the directory doc/ to a directory where formatted man pages reside. Note that your man command must be able to interpret already formatted man pages for this option. (j) Yet another options are "make package", which is a synonym for "make compile", "make install" and "make doc2man". Then there's "make dist", which makes new distribution files (this option is likely to be used by me -- a lot, I hope). Using the Graphics library in your own programs ----------------------------------------------- The classes and functions of the Graphics library are declared in the header files which are installed during a "make install" in the installation process. E.g., the class Gwin and its functions are declared in the header file gwin.h". You can include the header files in your C++ source files using, e.g., #include ; provided that the header files are installed in the system include directories. The actual code of the class functions is combined into one library libgraph.a. To make sure that this library is used by the linker, use the following flag as the last option of the commandline invoking gcc: gcc .....whatever options you may use... -lgraph This command will work if libgraph.a is installed in one of the the system library directories. The programs which are built with the Graphics library can only be run as root. The reason for this is the fact that VGAlib needs to obtain IO permissions; this is only possible as root. An attempt to run such a program as non-root will result in an error message from VGAlib, stating that the IO permissions could not be obtained. Copyright and other legal stuff ------------------------------- The documentation and the sources for the Graphics library are copyrighted by me. This is done to ensure that I keep the latest version. If you have suggestions, questions, bug reports etc., mail me and I will look into it if I have the time. Alternatively, implement a feature and mail me your code; if it's in the 'spirit' of the Graphics library, I will include it. Furthermore, there is *no* warranty on this software. As with everything that's free, there is absolutely no warranty. Last, this software is free and should remain so. You are not permitted to charge any amount for this software, not even the $5 for shipping.