by Grafix Ver. 1.4 7/97
=====================================
0. Getting && Installation
==========================
You may fetch it via ftp from the sunsite server or one of its mirrors under
sunsite.unc.edu:/pub/Linux/libs/X/c++libs/grafix-1.4.*
If you have any problems with it, please Email me (see address below)
a) gtar -xvzf grafix-1.4.tar.gz
(if you don't have "gtar" or GNUs "tar" version, use "gunzip" first and then
invoke "tar -xvf grafix")
This expands the tar file into some subdir like "grafix-1.4"
cd to this subdir and:
b) check "grafix.mk" for the correct paths for Xlib (X11R6 or X11R5) -> XPATH
and some include directories on your system.
Please, read the following text if you have any problems.
c) gmake allnew : to build all demo programs
(if you get compiling errors, see below)
d) gmake demorun : to invoke a run of all demos
1. What is "Grafix" ?
=====================
"Grafix" is a utility originally designed to help scientists in the
visualization of results of a computation, e.g. for numerical integrations of
partial differential equations.
It can be used, however, for any application that wants to use X-Windows for
drawing pictures, functions or other graphic objects in a convinient
interactive manner or even for writing a graphical user interface for any task.
Grafix should be considered as a layer between an application and the X Window
system built up of a bunch of basic classes as building elements.
The simplest way of using it is to define instances of these classes.
For more complicated programs the user has to define own derivations to the
basic clases.
- Grafix is based on Unix and the X Window system.
- Grafix does not use any commercial code, like Motif, so it is totally free.
- Grafix is been ported and tested for Linux and SunOS, with X11R5/R6
- Grafix is small and fast since it is pure functionality without any
superfluous additives.
- Grafix is completely written in C++ and to compile with g++ on both platforms
The object-oriented approach enables a quite simple way of introducing user
defined behaviour.
- Grafix includes classes for the basic operations to have a convinient window
management, like :
- windows with automatic restoring for complex drawings (backing store)
- several types of predefined button classes for different purposes :
quit_button, delete_button, help_button, callback_button, toggle_button,
instance_button, dump_button, hardcopy_button, ...
all the buttons have a Motif-like three dimensional shape
- popup-windows and pulldown-menus for selecting discrete values
- help popups can be bound to any window
- scrollbars for selecting coniguous values
- windows with real-valued co-ordinate systems where the user has not to
worry about pixel co-ordinates
- a simple edit window for entering strings
- simple file selection boxes for openening files interactively
for reading (with directory scan) and writing (query before overwrite)
- a predefined palette manager for color definitions that can be
implemented in any application
- as advanced class : an complete manager to handle the display
of 2-dim functions (given on a equidistant grid) as lattice or body
in arbitrary perpective, shadowing and details zooming.
- new : animator class : to store time sequences of two dimensional arrays
in a file (more than one, also 3-dim arrays can be treated as vector
of 2-dim arrays) and replay them like a video film.
This is at most useful for visualizing time consuming integration
procedures
- new : integrator class : very easy to use prototype to link any
numerical 2- or 3-dim FDE-integration program with the graphic interface
and playback feature
- new : scrolled windows of (nearly) arbitrary virtual size
- new : classes for displaying tree- and graph-structures, and as
application a very nice graphic class browser
(and a simple one "dir-tree")
- Grafix has some example programs to show the basic functions,eg
"win-demo", "edit-demo", "file-browser", "calc", "pal-demo", etc.
The simple ones should help the learner to understand the functionality :
hello, win-demo, edit-demo, file-browser, pal-demo, clock-demo, dir-tree
while the other provide also real functionality :
class-browser, file-browser, cursors, calc, one-dim, two-dim, replay
- The programs "one-dim", "two-dim", "three-dim", "replay"
give a complete model of some numerical integration methods for the one
or two dimensional advection equation (simple upstream method,
Smolarkievicz-method, Lax-Wendroff). They have several buttons and menus
for playing with some parameters and three-dim allows
to afterwards show the ongoing integration as animation.
These demos should be easily adopted to any one or two dimensional
set of differentional equation with time dependence (finite difference)
2. What is it NOT
=================
- it is not a commercial software, so I will not take any warranty for the
usability of the software
- it is not in a "ready to use" state, it requires the user to write own
C++-code (this should be obvious)
- I can give no guarantee to respond on error reports or queries for
improvements since my time for this task is limited. But I'll try my best
to help you.
3. What do you need to use "Grafix"
===================================
- You should have basic knowledge about C++ classes and what an X-window is.
Further knowledge about Xlib programming will be helpful but is not
necessary since I tried to encapsulate this in the classes.
- You need g++ to compile the code, other compilers possibly do not allow some
special constructs for passing multidimensional arrays as parameters.
These type casts could be easily substituted, however.
- You need Unix (SunOS, Linux) and X11R5 or X11R6.
Portations to other platforms are not my concern, since I have no
possibility to test them. But if you have gcc and X11 there should be no
major problems.
Reported platforms that work (possibly with minor adaptions):
SGI (Silicon Graphics, IRIX)
Sun , SunOS 5.3, Solaris 2.3, Solaris 2.4
Bull DPX/20 (PowerPC and AIX 3.2.5).
PC (Interactive Unix, ISC 4.0)
HP 9000/735 with HP/UX 9.03A
- you have to agree to the "GNU GENERAL PUBLIC LICENSE"
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION,
(see included standard file "COPYING" for details)
in order to use the program, copy, distribute or modificate it or parts
of the code. (If you intend to use it for proprietary programs,
please contact me, so we may find a solution.)
Additionally, I forbid the use of any part of the package
for military purposes and any portations to Win*ows-XX
4. How to start
===============
I strongly suggest starting with the example programs in the package.
They demonstrate nearly the complete functionality. Compile them, start
and play with them. Then have a look at the sources and try to understand
how they work.
- Have a look at the file "grafix.mk" if the paths for Xlib are correct for
your platform. On my Linux-PC I have "XPATH = /usr/X11R6", while the Sun
expects "XPATH = /opt/X11R6". BTW, X11R5 should also work.
If you want to make a port to a new hardware platform, please add
a new entry similiar to to the existing ones, eg.
ifeq ($(shell uname),myplatform)
XPATH = ....
LFLAGS = ....
CFLAGS = -I.... -DMYPLATFORM
endif
If possible, let me know about this, so I may include this in the next
release.
Another possible cause of compilation failure is that some special include
files for gcc are not found (regex.h). Then you should include
"-I./gccinc" in your CFLAGS
- To build all demos type :
for the first time "gmake depend"
and then "gmake"
- To let them all run consecutivly type :
"gmake demorun"
- read the file HOWTO for a detailed instruction of the installation
and a description of the use of Grafix.
5. Help sought !
================
Some extensive manuals would be very helpful for users, but I have no time
to write them. It would be nice to have eg. class descriptions and more
general info, possibly as an info-file or other online help (html-manual ?).
If anyone has the possibility to help me, please contact me per email.
6. Main changes since version 1.0 (from Feb. 95)
================================================
(see LOG.txt for details)
- event handling simplified, so each window class receives only the events
of interest
- new classes for text viewing (files.c)
- file-browser demo included
- clock_win : included
- main_window class allows additional arguments for positioning
- animator- and replay- functionality for saving and redisplaying results of
integration runs
- scrolled windows included
- Tree windows derivation
- class-browser as a complete demo for these
- dir-tree as simple demo for scrolled windows, and Tree windows
- some bug fixes : eg. the black background color on some displays
- compilation errorfree with gcc 2.6.3, and 2.7.0
- support of TrueColor modes (16bpp, 32bpp)
7. Main changes since version 1.2 (4.11.95), see LOG.txt
========================================================
(version 1.3 was an internal version and not released)
- in window.c : a hash table algorithm for mapping X-IDs to window pointers
now there is no more limit of the number of windows and they may be
constructed and deleted in any fashion !!!
- lattice : an isoline display mode implemented
- great new demos :
"earth" - rotating earth,
"font-browser" - browse through all X-fonts
"mandel" - the famous Mandelbrot-Set
- some minor bugfixes, improvements and additions
- installation : the tar-File (tar.gz) now expands automatically into a new
directory "grafix-1.4"
8. Author
=========
---------------------------------------------------------------------------
... always look on the bright side of life ... (Monty Python)
---------------------------------------------------------------------------
Wolfgang Koehler wo...@gfz-potsdam.de
GeoForschungsZentrum Potsdam, Germany, Projekt CHAMP Tel: (0331)2817928