Copyright (C) 1992 The Board of Trustees of The Leland Stanford
Junior University. All Rights Reserved.
Disclaimer Notice
The items furnished herewith were developed under the sponsorship
of the U.S. Government. Neither the U.S., nor the U.S. D.O.E., nor the
Leland Stanford Junior University, nor their employees, makes any war-
ranty, express or implied, or assumes any liability or responsibility
for accuracy, completeness or usefulness of any information, apparatus,
product or process disclosed, or represents that its use will not in-
fringe privately-owned rights. Mention of any product, its manufactur-
er, or suppliers shall not, nor is it intended to, imply approval, dis-
approval, or fitness for any particular use. The U.S. and the Univer-
sity at all times retain the right to use and disseminate the furnished
items for any purpose whatsoever. Notice 91 02 01
Hippoplotamus
=============
Hippoplotamus (hippo) is a histogramming library based on n-tuples.
The original implementation was by Jonas Karlsson. It is being written at
SLAC by Paul Rensing, Paul Kunz, Mike Gravina, plus contributions from
Tom Pavel and others. It is designed to be used as an n-tuple collection
library and as the guts of an interactive application to view n-tuples.
Building hippo
==============
We have provided some ways of building hippo. You can also make it
yourself.
A minimum set of files which provide support for collecting n-tuples
only is:
hippontuple.c hippoio.c hippoxdr.c hippoutil.c ntuple-parse.c
hippo.h hippostruct.h hippoxdr.h hippoutil.h
There are three utility programs:
nt2text.c text2nt.c hb2hippo.f
UNIX
====
This package includes a makefile for UNIX machines. The file is built
with machine independent parts (Makefile and make.common) and a machine
dependent part (make.<machine>). The machine architecture is determined by
the script "architecture" and is set when make.common is called from
Makefile. Architectures on which we have tested hippo are sun, next,
ultrix, sgi and aix (rs6000). If you are adding a new machine, check that
architecture gives a sensible answer.
Because there are a number of plot drivers available, and one may want
more than one driver available on a given architecture, we have designed
the make file to build different libraries for the different (major)
drivers. For example, on a NeXT, you would build only libhippoNext.a, while
on a Sun, you might build libhippoX11.a and libhippoXIV.a (the Interviews
driver). If you don't have any of these packages to link to, you could
build a library (make target "hippo") which only contains the PostScript
and line printer drivers, no screen drivers.
There are a number of macros which may need to be tailored to your
system. The machine dependency file is included late so that it can
override any macro defined in Makefile.
in make.common:
SRC_DIR - this is the directory containing the source code
LIB_INSTALLDIR - directory in which to install the libraries
INC_INSTALLDIR - directory in which to install the header files
LIB_DIR - directory in which the libraries are built. Is include as a -L
option when linking, so it should be defined ("." means current
directory).
in make.<flavor>:
CC, CPLUSPLUS - your compiler commands
FC - your FORTRAN compiler
FBINDINGS - the Fortran binding files. Set to blank here if you don't have
a Fortran compiler.
LIB_LIST - list of libraries to build for this machine
DEBUGLIB_LIST - list of debug libraries to build
FORTRAN
-------
We have provided a set of FORTRAN bindings for some of the function
calls in hippo. If you don't have FORTRAN, comment out the macro FBINDINGS,
or override the definition (set it to blank) in the machine dependent file.
Plot Drivers
------------
Hippo provides a number of plot drivers, which can be select for
compilation in any combination. See make.next or make.sun4 for examples.
DrvrName CodeFile IncludeFile C_Define Description
-------------------------------------------------------------------------------
LPR (none) (none) (none) line printer driver
PS (none) (none) (none) PostScript to file
NEXT hippoplotNeXT.c hippoplotNeXT.h _NEXT_PLOT_ NeXT DPS driver
hippowrapsps.c hippowrapsps.h (from hippowraps.psw)
UNIXPLOT hippoplotUP.c hippoplotUP.h _UNIXPLOT_PLOT_ UNIXPlot driver
XIVPLOT hippoplotXIV.cc hippoplotXIV.h _XIVPLOT_ Interviews driver
X11PLOT hippoplotX11.cc hippoplotX11.h _X11PLOT_ X-11 driver (R4)
By default, one of the screen drivers is included in each library, eg.
libhippoX11.a is built using the X11PLOT driver.
If you wish to have a combination of drivers, you could build your own library.
A driver must be selected at compile time in order to be able to use it in
a program. To select a driver:
1) add the codefile to MACH_DEP_MEMS in the form "$(LIBRARY)(<codefile>.o)",
where <codefile>.o is the compiled object file of the files listed above.
2) add the include file to DRVR_INCS
3) add the C macro definition for C_Define (above) to PLOTCFLAGS,
eg. -D_NEXT_PLOT_
Finally, you should choose one default plot driver by defining the C macro
DEF_PLOT_DRVR; eg. -DDEF_PLOT_DRVR=NEXT (use the DrvrName from above). LPR and
PS are always defined and one should be used as a default if you don't want any
other driver defined.
Make Targets
------------
all - build the regular and debug libraries and utilities
libs - (default) build the standard libraries
debuglibs - build the debug libraries
<name> - build library lib<name>.a, eg. hippoX11, hippoNext.debug,
hippoXIV.profile
util - build the text/hippo converter programs
clean - delete backup files
install - copy libraries and certain include files to specified place
hb2hippo - an HBOOK to hippo converter. Needs CERN's PackLib.
test - run a few tests to see that hippo is working.
VMS
===
We have included an MMS file for VMS under the name make.vms (this does
not need the file Makefile). The file is written to compile with the X11
driver. You may need to change the logicals defined under .First to point to
the correct directories (this is for RPC include files). Otherwise, many of the
macro are the same as for the UNIX makefile. We do not change the name of the
the Fortran file hippof.f.
When linking a program with hippo on VMS, you will need the RPC and
Multinet libraries. On my system, they are located at
multinet_root:[multinet.library]rpc.olb
multinet_root:[multinet]multinet_socket_library.exe
(The socket library is really only needed to resolve bcopy and bset,
something that Multinet should have put in the RPC library). The file
hippo.opt is used to specify these libraries.
The C macro GLOB_QUAL is defined to be "noshare" on VMS. This should allow one
to build a sharable library.
Miscellaneous Files
===================
architecture - determine machine type on UNIX.
example.hippo - example hippo ntuple in binary format (used for
make test).
example.hiptxt - example hippo ntuple in text format (used in
make test).
fhippo.c, hippof.f - the FORTRAN binding files.
getarg.c - provide proper version of FORTRAN callable getarg()
for NeXT. Used only in hb2hippo.
hippo.opt - options file for VAX/VMS linker.
hshrtnm.h - header file with short names for most of the hippo
functions. (necessary on IBM VM)
h_test.c - program to test basic display functions.
h_test.out - reference output of h_test
h_testX11.c - program to exercise the X11 driver.
Problems, Changes and Bug Reports
=================================
We are very interested in hearing about bugs and improvements.
If you find a bug, please send mail to
"hippo_bug@ebnextk.slac.stanford.edu" and we will do our best. Please try
to be as specific as possible.
If you have any suggestions or wish to make some contribution (eg. a
new plot driver), please contact the authors. Send mail to
"hippo_comment@ebnextk.slac.stanford.edu".
Registration
============
It is recommended that if you are using hippo, you send mail to
hippo_comment to "register" your copy. This will allow us to inform you
about major updates and bug fixes.
X11 Driver for Hippo
====================
The X Driver for Hippo uses only standard XLIB calls and should work with
X11R4 and X11R5. There are a number of known bugs and limitations which are
documented below.
*** If you are not familiar with X, please look at x11test for a simple
example of using this driver.
Usage
-----
The compile flag to select the X driver is:
_X11_PLOT_
To select X as the output device use...
h_setPlotDrvr(X11PLOT);
When calling h_plot to draw a hippo plot to an X window, four additional
arguments must be given to the h_plot call.
int h_plot(display disp, Display *dpy, Screen *scrn, Drawable Wind, GC gc);
Where:
disp is the Hippo plot to be drawn.
dpy is the X display pointer.
scrn is the X screen pointer for the screen on which the window resides
wind is the window or Pixmap into which the plot is to be drawn.
gc is a graphics context suitable for use with wind. The graphics
context is used to specify the background color for the plot and
can also be used to specify a clip mask (may be useful when handling
exposure events).
The plot will be scaled to fill the specified drawable. Note that this
routine is intended to be used as a fairly low level routine in some
application requiring X display of histograms. The application is
responsible for handling expose events, and for dealing with redrawing the
plot if the window is resized. A simple example of how to use the X11
driver is given in the demonstration program x11test supplied with hippo.
Known bugs and limitations
--------------------------
A number of bugs and limitations are known to exist in this version of
hippo's X11 driver. These are documented below. Any offers to fix or
improve any of these features will be warmly received. The assumption made
in designing hippo's X11 driver is that it will be used for interactive
applications where very high speed redrawing of the display is required.
The desire to avoid duplication of potentially time-consuming tasks is what
leads to a number of the limitiations below.
1) Only Color and Black and White X servers supported.
The current version of the X11 driver only supports color X servers with
dynamically allocatable color maps, and black and white servers. All other
servers (eg grey scale or displays with static color maps) are treated as
if they were black and white.
2) Crude recovery for unallocatable color map entries.
If the X11 driver is unable to allocate all of the color map entries that
it wants it issues a one time error message, but then continues execution,
resulting in displays which will have "random" colors. A better
implementation would attempt to adjust its display philosophy to the number
of colors available. To display both color and gray scale plots requires a
total of nearly 200 hundred color map entries, so a screen depth of a least
8 is required.
3) Crude lego plot.
The lego plot implemented in the current version of the X11 driver is
intended merely as a proof of principle, rather than a full implementation.
There is no support for labeling the axes, for changing the Z axis or for
changing the stereo angle. In addition the drawing speed could be improved.
Also the plot doesn't always fir in the window
4) Text handling problems.
For flexiblity the current version of the X11 driver works with all version
of X after X11R4. No use has been made of the more advanced text handling
features of X11R5. The main limitations imposed by this are in text sizing
and rotated text. The X11 driver attempts to choose an appropriate sized
font, but this process does not always work perfectly. Rotated text is
handled in a manner which requires copying pixmaps between the server and
client. To speed this process up the X11 driver maintains a cache of
previously copied strings which it attempts to reuse. This normally works
ok, but if some graphics attribute (such as the background color) is
changed dynamically the rotated text may be drawn with the old attribute.
This could be improved by generating a version of the X11 driver which uses
X11R5 when it is available.
5) Support for multiple display devices.
The first time a plot is drawn to an X device, the X11 driver caches
certain characteristics of the server, such as which fonts are available
and what type of device it is. If multiple display devices with different
characteristics are used from the same job this will cause problems.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.