207 lines
9.5 KiB
Plaintext
207 lines
9.5 KiB
Plaintext
=============================================================================
|
|
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 <gwin.h>; 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.
|