Geant4 User's Guide For Application Developers Visualization

8.2.1 Installing Visualization Drivers

Note that not all drivers can be installed on all systems; Table 8.1 in Section 8.3 lists all the available drivers and the platforms on which they can be installed. For any of the visualization drivers to work, the corresponding graphics system must be installed beforehand.

Unless the environment variable G4VIS_NONE is set to "1", visualization drivers that do not depend on external libraries are automatically incorporated into Geant4 libraries during their installation. (Here "installation of Geant4 libraries" means the generation of Geant4 libraries by compilation.) The automatically incorporated visualization drivers are: DAWNFILE, HepRepFile, HepRepXML, RayTracer, VRML1FILE, VRML2FILE and ATree and GAGTree.

The OpenGL, OpenInventor and RayTracerX drivers are not incorporated by default. Nor are the DAWN-Network and VRML-Network drivers, because they require the network setting of the installed machine. In order to incorporate them, the environment variables "G4VIS_BUILD_DRIVERNAME_DRIVER" should be set to "1" before installing the Geant4 libraries:

     setenv G4VIS_BUILD_OPENGLX_DRIVER      1  # OpenGL-Xlib driver
     setenv G4VIS_BUILD_OPENGLXM_DRIVER     1  # OpenGL-Motif driver 
     setenv G4VIS_BUILD_OIX_DRIVER          1  # OpenInventor-Xlib driver
     setenv G4VIS_BUILD_RAYTRACERX_DRIVER   1  # RayTracer-XLib driver
     setenv G4VIS_BUILD_DAWN_DRIVER         1  # DAWN-Network driver
     setenv G4VIS_BUILD_VRML_DRIVER         1  # VRML-Network

8.2.2 How to Realize Visualization Drivers in an Executable

In order to realize visualization drivers, you must instantiate and initialize a subclass of G4VisManager that implements the pure virtual function RegisterGraphicsSystems(). This subclass must be compiled in the user's domain to force the loading of appropriate libraries in the right order. The easiest way to do this is to use G4VisExecutive, a provided class with included implementation. G4VisExecutive is sensitive to the G4VIS_USE... variables mentioned below.

If you do wish to write your own subclass, you may do so. You will see how to do this by looking at G4VisExecutive.icc. A typical extract is:

     ...
       RegisterGraphicsSystem (new G4DAWNFILE);
     ...
     #ifdef G4VIS_USE_OPENGLX
       RegisterGraphicsSystem (new G4OpenGLImmediateX);
       RegisterGraphicsSystem (new G4OpenGLStoredX);
     #endif
     ...

If you wish to use G4VisExecutive but register an additional graphics system, XXX say, you may do so either before or after initializing:

     visManager->RegisterGraphicsSytem(new XXX);
     visManager->Initialize();

Source listing 8.2.2
An example of a typical main() function is given below.

By default, you get the DAWNFILE, HepRepFile, RayTracer, VRML1FILE, VRML2FILE, ATree and GAGTree drivers. Additionally, you may choose from the OpenGL-Xlib, OpenGL-Motif, OpenInventor, RayTracerX, DAWN-Network and VRML-Network drivers, each of which can be selected by setting the proper environment variable:

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

(Of course, this has to be chosen from the set incorporated into the Geant4 libraries during their compilation.) Unless the environment variable G4VIS_NONE is set, these set C-pre-processor flags of the same name.

Also, unless the environment variable G4VIS_NONE is set, the C-pre-processor flag G4VIS_USE is always set by default. This flag is available in describing the main() function.

You may have to set additional environment variables for your selected visualization drivers and graphics systems. For example, the OpenGL driver may require the setting of OGLHOME which points to the location of the OpenGL libraries. For more details, see Section 8.3 "Visualization Drivers" and pages linked from there.

A Sample Set-up File

 ############################################################
 # Main Environment Variables for GEANT4 with Visualization #
 ############################################################

 ### Platform
 setenv G4SYSTEM Linux-g++

 ### CLHEP base directory
 setenv CLHEP_BASE_DIR /opt/local

 ### OpenGL base directory
 setenv OGLHOME /usr/X11R6
 
 ### G4VIS_BUILD 
 ###   Incorporation of OpenGL-Xlib and OpenGL-Motif drivers
 ###   into Geant4 libraries.
 setenv G4VIS_BUILD_OPENGLX_DRIVER 1
 setenv G4VIS_BUILD_OPENGLXM_DRIVER 1

 ### G4VIS_USE
 ###   Incorporation of OpenGL-Xlib and OpenGL-Motif drivers
 ###   into Geant4 executables.
 setenv G4VIS_USE_OPENGLX       1
 setenv G4VIS_USE_OPENGLXM      1

 ### Viewer for DAWNFILE driver 
 ### Default value is "dawn".  You can change it to, say,
 ### "david" for volume overlapping tests
 # setenv G4DAWNFILE_VIEWER david

 ### Viewer for VRMLFILE drivers 
 setenv G4VRMLFILE_VIEWER vrmlview

 ########## end 

8.2.3 Visualization Manager

8.2.4 How to Write the main() Function

Source listing 8.2.2 shows the form of the main() function.

 //----- C++ source codes: Instantiation and initialization of G4VisManager

 .....
 // Your Visualization Manager 
 #include "G4VisExecutive.hh"
 .....

 // Instantiation and initialization of the Visualization Manager
 #ifdef G4VIS_USE
 G4VisManager* visManager = new G4VisExecutive;
 visManager -> initialize ();
 #endif

 .....
 #ifdef G4VIS_USE
 delete visManager;
 #endif

 //----- end of C++ 

Alternatively, you can implement an empty RegisterGraphicsSystems() function, and register visualization drivers you want directly in your main() function. See Source listing 8.2.3.

 //----- C++ source codes: How to register a visualization driver directly
 //                        in main() function

 .....
 G4VisManager* visManager = new G4VisExecutive;
 visManager -> RegisterGraphicsSystem (new MyGraphicsSystem);
 .....
 delete visManager

 //----- end of C++ 

DO NOT FORGET to delete the instantiated Visualization Manager by yourself. Note that a graphics system for Geant4 Visualization may run as a different process. In that case, the destructor of G4VisManager might have to terminate the graphics system and/or close the connection.

We recommend that the instantiation, initialization, and deletion of the Visualization Manager be protected by C-pre-processor commands, as in the novice examples. The C-pre-processor macro G4VIS_USE is automatically defined unless the environment variable G4VIS_NONE is set. This assumes that you are compiling your Geant4 executable with the standard version of GNUmakefile found in the config directory.

Source listing 8.2.4 shows an example of the main() function available for Geant4 Visualization.

 //----- C++ source codes: An example of main() for visualization
 .....
 #include "G4VisExecutive.hh"
 .....

 int main() 
 {
      // Run Manager
      G4RunManager * runManager = new G4RunManager;

      // Detector components
      runManager->set_userInitialization(new MyDetectorConstruction);
      runManager->set_userInitialization(new MyPhysicsList);

      // UserAction classes.
      runManager->set_userAction(new MyRunAction);
      runManager->set_userAction(new MyPrimaryGeneratorAction);
      runManager->set_userAction(new MyEventAction);
      runManager->set_userAction(new MySteppingAction);

 #ifdef G4VIS_USE
      G4VisManager* visManager = new G4VisExecutive;
      visManager -> initialize ();
 #endif

      // Event loop
      // Define (G)UI terminal
      G4UIsession * session = new G4UIterminal
      session->sessionStart();

      delete session;
      delete runManager;

 #ifdef G4VIS_USE
      delete visManager;
 #endif

      return 0;
 }

 //----- end of C++ 

Useful information on incorporated visualization drivers can be displayed in initializing the Visualization Manager. This is done by setting the verbosity flag to an appropriate string:

   Simple graded message scheme - give first letter or a digit:
    0) quiet,         // Nothing is printed.
    1) startup,       // Startup and endup messages are printed...
    2) errors,        // ...and errors...
    3) warnings,      // ...and warnings...
    4) confirmations, // ...and confirming messages...
    5) parameters,    // ...and parameters of scenes and views...
    6) all            // ...and everything available.

  ...
  G4VisManager* visManager = new G4VisExecutive ();
  visManager -> SetVerboseLevel (1);
  visManager -> Initialize ();
  ...