$Id: README,v 1.12 2005/02/15 14:08:11 johna Exp $

Note: Specific graphics systems must be instantiated in a high level
library to avoid circular dependencies.  Also, some specifically need
additional external libararies that the user must supply.  Therefore we
ask the user to implement RegisterGraphicsSystems() in a subclass of
G4VisManager.  We have to wait for the subclass to instantiate so
RegisterGraphicsSystems() cannot be called from G4VisManager's
constructor; it is called from G4VisManager::Initialise().  So we ask
the user:
  (a) to write a subclass of G4VisManager and implement
      RegisterGraphicsSystems().  This is most easily done by
      including G4VisExecutive.hh.
  (b) instantiate the subclass.
  (c) invoke the Initialise() method of the subclass.
For example, in your main():
  ...
#ifdef G4VIS_USE
  // Instantiate and initialise Visualization Manager.
  G4VisManager* visManager = new G4VisExecutive;
  visManager -> SetVerboseLevel (Verbose);
  visManager -> Initialise ();
#endif
  // (Don't forget to delete visManager;)
  ...
See, for example, examples/novices/N02/exampleN02.cc.

1) Decide which graphics systems drivers you want.  By default you get:
     ASCIITree, DAWNFILE, GAGTree, HepRepFile, HepRepXML, RayTracer, VRMLFILE.

   For others, the choice depends on what graphics libraries you have
   access to.  Set the appropriate environment variables.  Here are
   the current possibilities (see example "rc" script in Appendix A):

     setenv G4VIS_BUILD_DAWN_DRIVER         1  # Uses Fukui Renderer DAWN 
                                               #  with network connection
                                               #  (for remote visualization)

     setenv G4VIS_BUILD_OPENGLX_DRIVER      1  # Uses OpenGL libraries
     setenv G4VIS_BUILD_OPENGLXM_DRIVER     1  # Uses OpenGL and Motif 
                                               #  libraries

     setenv G4VIS_BUILD_OIX_DRIVER          1  # Uses OpenInventor X11

     setenv G4VIS_BUILD_VRML_DRIVER         1  # Sends  VRML ascii files
                                               #  to a remote host 
                                               #  (for remote visualization)

   Unless an environment variable G4VIS_NONE is set, setting any of
   these sets a C-pre-processor flag of the same name; also
   C-pre-processor flag G4VIS_BUILD is set.

   In some cases you will need additional variables, e.g.:

     setenv DAWN_HOME /user/local/bin
     set path=( $path $DAWN_HOME )

     setenv OGLHOME /usr/local
     setenv OGLFLAGS "-I$(OGLHOME)/include"
     setenv OGLLIBS "-L$OGLHOME/lib -lMesaGLU -lMesaGL"

     setenv OIVHOME /usr/local
     
   If you are going to use widgets, then you might need to set the
   environment variable:

     setenv XKEYSYMDB /usr/lib/X11/XKeysymDB

2) Compile and build the Geant4 libraries:

     cd $G4INSTALL/source
     gmake

   If you have already built the Geant4 libraries and only wish to
   include/change visualization, you need to rebuild visualization and
   interfaces (since some graphics drivers share resources, such as X
   event handling, with interfaces) and rebuild the libary map (in
   case new libraries have been made):

     cd $G4INSTALL/source/visualization
     gmake clean
     gmake
     cd $G4INSTALL/source/interfaces
     gmake clean
     gmake
     cd $G4INSTALL/source
     gmake libmap

   *******************************************************************
   NOTE THAT IF YOU CHANGE ANY OF THE ABOVE ENVIRONMENT VARIABLES THEN
   YOU WILL HAVE TO REPEAT THE ABOVE OPERATIONS, INCLUDING REBUILDING
   THE LIBRARY MAP.
   *******************************************************************


3) Decide which graphics systems you want to use in your particular
   excutable.  By default you get:
     ASCIITree, DAWNFILE, GAGTree, HepRepFile, RayTracer, VRMLFILE.

   Of course, this has to be chosen from the set you
   installed in (1,2) above.  Here are the current possibilities:

     setenv G4VIS_USE_DAWN         1
     setenv G4VIS_USE_OPENGLX      1
     setenv G4VIS_USE_OPENGLXM     1
     setenv G4VIS_USE_OIX          1
     setenv G4VIS_USE_VRML         1

   Unless an environment variable G4VIS_NONE is set, setting any of
   these sets a C-pre-processor flag of the same name; also,
   C-pre-processor flag G4VIS_USE is set.C-pre-processor flag - see
   examples/novices/N02/exampleN02.cc to see a use of this.

   The graphics systems are instantiated and registered when you
   execute G4VisExecutive::Initialise() (or G4VisExecutive::Initialize()).
   Note also that you can register graphics systems directly, e.g.,
   pVisManager->RegisterGraphicsSystem ( new DAWNFILE ).  You can also
   register your own graphics system, e.g.,
   pVisManager->RegisterGraphicsSystem (new MyGraphicsSystem).


4) Compile and link your code.  This assumes, in the current
   directory, you have a GNUmakefile like
   $G4INSTALL/examples/novice/N01/GNUmakefile and your main program.
   Also your header files are in include/ and your source files are in
   src/ - see, e.g., $G4INSTALL/examples/novice/N01 (this is the
   "canonical" user code structure).

     gmake clean
     gmake

   *******************************************************************
   NOTE THAT IF YOU CHANGE ANY OF THE ABOVE ENVIRONMENT VARIABLES THEN
   YOU WILL HAVE TO REPEAT THE ABOVE gmake clean AND gmake COMMANDS, OR
   AT THE VERY LEAST, RECOMPILE YOUR PROGRAM THAT INCLUDES G4VisExecutive.hh,
   E.G.,
      touch myprog.cc; gmake
   *******************************************************************


5) To run:

     setenv DISPLAY <local IP address>:0
     $G4WORKDIR/bin/$G4SYSTEM/myprog


Appendix A: An "rc" example
---------------------------

---------------------- g4rc ------------------------------------------ 
## Must be run from a directory *containing* geant4/.
## It must be "sourced" from a Bourne/ksh.bash shell using `. <pathname>'
##   or `source <pathname>'.
## G4INSTALL becomes geant4.
## G4BIN, etc., in some apprpriate subdirectory of $disc1

disc1=/scratch/GEANT4
if [ ! -e $disc1/$thisbase ]; then
  mkdir $disc1/$thisbase
fi
if [ ! -e $disc1/$thisbase/geant4 ]; then
  mkdir $disc1/$thisbase/geant4
fi
disc2=/mnt/disc2

if [ -e `pwd`/geant4 ]; then

thiswd=`pwd`
thisbase=`basename $thiswd`
export G4INSTALL=$thiswd/geant4
env | grep G4INSTALL=
export G4WORKDIR=$G4INSTALL
export G4BIN=$disc1/$thisbase/geant4/bin
env | grep G4BIN=
export G4LIB=$disc1/$thisbase/geant4/lib
env | grep G4LIB=
export G4TMP=$disc1/$thisbase/geant4/tmp
env | grep G4TMP=
export G4SYSTEM=Linux-g++
export G4LEVELGAMMADATA=$G4INSTALL/data/PhotonEvaporation

export G4DEBUG=1
export CLHEP_BASE_DIR=/usr/local
env | grep G4DEBUG
env | grep CLHEP
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CLHEP_BASE_DIR/lib

##export CVSROOT=:pserver:allison@g4cvs.cern.ch:/afs/cern.ch/sw/geant4/cvs
export CVSROOT=/afs/cern.ch/sw/geant4/cvs
export CVSEDITOR=emacs

########## DAWN (Fukui) Renderer
export G4VIS_BUILD_DAWN_DRIVER=1
export G4VIS_USE_DAWN=1
export DAWN_BSD_UNIX_DOMAIN=1
export DAWN_GUI_ALWAYS=1
#export DAWN_HOME=/home/johna/GEANT4/DAWN  # Now in /usr/local.
#export G4DAWNFILE_VIEWER=NONE # Uncomment if DAWN is not available.
#export PATH=$PATH:$DAWN_HOME  # Now in /usr/local.

########### OpenGL
export G4VIS_BUILD_OPENGLX_DRIVER=1
export G4VIS_USE_OPENGLX=1
export G4VIS_BUILD_OPENGLXM_DRIVER=1
export G4VIS_USE_OPENGLXM=1
### export XKEYSYMDB=/usr/lib/X11/XKeysymDB
export OGLHOME=/usr/X11

########### OpenInventor
export G4VIS_BUILD_OIX_DRIVER=1
export G4VIS_USE_OIX=1
export OIVFLAGS="-I$disc2/HEPVis/new/include -DINVENTOR2_1 -I$disc2/SoFree/new/include"
export OIVLIBS="-L$disc2/HEPVis/new/Linux-gxx-SF -lHEPVis -L$disc2/SoFree/new/Linux-gxx -lSoFree"
export SOFREEUSER=$disc2/SoFree/new/user/

############ VRML
export G4VIS_USE_VRML=1
export G4VIS_BUILD_VRML_DRIVER=1

########### Interfaces
export G4UI_BUILD_TERMINAL_SESSION=1
export G4UI_USE_TERMINAL=1
export G4UI_BUILD_GAG_SESSION=1
export G4UI_USE_GAG=1
export G4UI_BUILD_XM_SESSION=1
export G4UI_USE_WO=1
### #export G4UI_BUILD_XAW_SESSION=1
### #export G4UI_USE_XAW=1

############ Persistency
# export G4USE_HEPODBMS=1
# . $G4INSTALL/examples/extended/persistency/PersistentEx01/g4odbms_setup.sh
# export OS=`uname`
# oocheckls -notitle `hostname` || \
#            oolockserver -notitle -noauto

else
 echo No geant4 here.
fi


Appendix B: Sample session
--------------------------

The Visualization Manager has been constructed with verbosity == c
(confirmations).

RunManager is constructing....

*************************************************************
 Geant4 version $Name: geant4-07-01 $   (17-December-2004)
                      Copyright : Geant4 Collaboration
                      Reference : NIM A 506 (2003), 250-303
                            WWW : http://cern.ch/geant4
*************************************************************

Visualization Manager instantiating...
Visualization Manager initialising...
Registering graphics systems...
G4VisManager::RegisterGraphicsSystem: ASCIITree (ATree) registered.
G4VisManager::RegisterGraphicsSystem: DAWNFILE (DAWNFILE) registered.
G4VisManager::RegisterGraphicsSystem: GAGTree (GAGTree) registered.
G4VisManager::RegisterGraphicsSystem: G4HepRep (HepRepXML) registered.
G4VisManager::RegisterGraphicsSystem: G4HepRepFile (HepRepFile) registered.
G4VisManager::RegisterGraphicsSystem: RayTracer (RayTracer) registered.
G4VisManager::RegisterGraphicsSystem: VRML1FILE (VRML1FILE) registered.
G4VisManager::RegisterGraphicsSystem: VRML2FILE (VRML2FILE) registered.
G4VisManager::RegisterGraphicsSystem: OpenGLImmediateX (OGLIX) registered.
G4VisManager::RegisterGraphicsSystem: OpenGLStoredX (OGLSX) registered.
G4VisManager::RegisterGraphicsSystem: OpenGLImmediateXm (OGLIXm) registered.
G4VisManager::RegisterGraphicsSystem: OpenGLStoredXm (OGLSXm) registered.
G4VisManager::RegisterGraphicsSystem: OpenInventorXt (OIX) registered.

You have successfully chosen to use the following graphics systems.
Current available graphics systems are:
  ASCIITree (ATree)
  DAWNFILE (DAWNFILE)
  GAGTree (GAGTree)
  G4HepRep (HepRepXML)
  G4HepRepFile (HepRepFile)
  RayTracer (RayTracer)
  VRML1FILE (VRML1FILE)
  VRML2FILE (VRML2FILE)
  OpenGLImmediateX (OGLIX)
  OpenGLStoredX (OGLSX)
  OpenGLImmediateXm (OGLIXm)
  OpenGLStoredXm (OGLSXm)
  OpenInventorXt (OIX)
...