source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Visualization/visexecutable.xml

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Updates for Qt: Laurent Garnier, Dec-2008             -->
<!--    Typo correction : Laurent Garnier, Dec-2009           -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.VisAddExe">
<title>
Adding Visualization to Your Executable
</title>

<para>
This section explains how to incorporate your selected
visualization drivers into the <literal>main()</literal> function and create
an executable for it. In order to perform visualization with your
Geant4 executable, you must compile it with realized visualization
driver(s). You may be dazzled by the number of choices of
visualization driver, but you need not use all of them at one time.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAddExe.InstDrv">
<title>
Installing Visualization Drivers
</title>

<para>
Depending on what has been installed on your system, several kinds
of visualization driver are available. One or many drivers may be
chosen for realization in compilation, depending on your
visualization requirements. Features and notes on each driver are
briefly described in <xref linkend="sect.VisDrv" />
"<emphasis role="bold">Visualization Drivers</emphasis>", 
along with links to detailed web pages for the various drivers.
</para>

<para>
Note that not all drivers can be installed on all systems; 
<xref linkend="table.VisDrv_1" /> in 
<xref linkend="sect.VisDrv" /> 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.
</para>

<para>
Unless the environment variable <literal>G4VIS_NONE</literal> 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.
</para>

<para>
The OpenGL, Qt, 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
"<literal>G4VIS_BUILD_DRIVERNAME_DRIVER</literal>" should be set to
"<literal>1</literal>" before installing the Geant4 libraries:

<informalexample>
<programlisting>
     setenv G4VIS_BUILD_OPENGLX_DRIVER      1  # OpenGL-Xlib driver
     setenv G4VIS_BUILD_OPENGLXM_DRIVER     1  # OpenGL-Motif driver 
     setenv G4VIS_BUILD_OPENGLQT_DRIVER     1  # Qt 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
</programlisting>
</informalexample>
</para>

<para>
Unless the environment variable <literal>G4VIS_NONE</literal> is set to "1",
setting any of the above variables sets a C-pre-processor flag of
the same name. Also the C-pre-processor flag <literal>G4VIS_BUILD</literal>
is set (see config/G4VIS_BUILD.gmk), which incorparates the
selected driver into the Geant4 libraries.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAddExe.RealVisDrv">
<title>
How to Realize Visualization Drivers in an Executable
</title>

<para>
You can realize and use any of the visualization driver(s) you want
in your Geant4 executable, provided they are among the set
installed beforehand into the Geant4 libraries. A warning will
appear if this is not the case.
</para>

<para>
In order to realize visualization drivers, you must instantiate
and initialize a subclass of <literal>G4VisManager</literal> that implements
the pure virtual function <literal>RegisterGraphicsSystems()</literal>. 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 <literal>G4VisExecutive</literal>, a provided class with
included implementation. <literal>G4VisExecutive</literal> is sensitive to
the <literal>G4VIS_USE...</literal> variables mentioned below.
</para>

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

<informalexample>
<programlisting>
     ...
       RegisterGraphicsSystem (new G4DAWNFILE);
     ...
     #ifdef G4VIS_USE_OPENGLX
       RegisterGraphicsSystem (new G4OpenGLImmediateX);
       RegisterGraphicsSystem (new G4OpenGLStoredX);
     #endif
     ...
</programlisting>
</informalexample>
</para>

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

<informalexample>
<programlisting>
     visManager-&gt;RegisterGraphicsSytem(new XXX);
     visManager-&gt;Initialize();
</programlisting>
</informalexample>
</para>

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

<informalexample>
<programlisting>
     setenv G4VIS_USE_OPENGLX      1
     setenv G4VIS_USE_OPENGLXM     1
     setenv G4VIS_USE_OPENGLQT     1
     setenv G4VIS_USE_OIX          1
     setenv G4VIS_USE_RAYTRACERX   1
     setenv G4VIS_USE_DAWN         1
     setenv G4VIS_USE_VRML         1
</programlisting>
</informalexample>
</para>

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

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

<para>
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 <literal>OGLHOME</literal> which
points to the location of the OpenGL libraries. For more details,
see <xref linkend="sect.VisDrv" /> 
"<emphasis role="bold">Visualization Drivers</emphasis>" and 
pages linked from there.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAddExe.SampSetup">
<title>
A Sample Set-up File
</title>

<para>
The following can be part of the user's <literal>.cshrc</literal> or
<literal>.tcshrc</literal> file on a Linux platform to configure the
environment for creating Geant4 executables available for Geant4
visualization. This sample is shown only as an example; it may NOT
correspond to a specific platform configuration and does NOT apply
in general for any specific setup !

<example id="programlist_VisAddExe_1">
<title>
Part of a sample <literal>.cshrc</literal> setup file for the Linux platform.
</title>

<programlisting>
 ############################################################
 # 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 
</programlisting>
</example>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAddExe.VisMan">
<title>
Visualization Manager
</title>

<para>
Visualization procedures are controlled by the "Visualization
Manager", a class which must inherit from <emphasis>G4VisManager</emphasis>
defined in the visualization category. Most users will find that
they can just use the default visualization manager,
<emphasis>G4VisExecutive</emphasis>. The Visualization Manager accepts users'
requests for visualization, processes them, and passes the
processed requirements to the abstract interface, i.e., to the
currently selected visualization driver.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAddExe.WrtMain">
<title>
How to Write the <literal>main()</literal> Function
</title>

<para>
In order for your Geant4 executable to perform visualization, you
must instantiate and initialize "your" Visualization Manager in the
<literal>main()</literal> function. The core of the Visualization Manager is
the class <literal>G4VisManager</literal>, defined in the visualization
category. This class requires that one pure virtual function be
implemented, namely, <literal>void RegisterGraphicsSystems()</literal>. The
easiest way to do this is to use <literal>G4VisExecutive</literal>, as
described above (but you may write your own class - see above).
</para>

<para>
<xref linkend="programlist_VisAddExe_2" /> shows the form of the 
<literal>main()</literal> function.

<example id="programlist_VisAddExe_2">
<title>
The form of the <literal>main()</literal> function.
</title>

<programlisting>
 //----- 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 -&gt; initialize ();
 #endif

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

 //----- end of C++ 
</programlisting>
</example>
</para>

<para>
Alternatively, you can implement an empty
<literal>RegisterGraphicsSystems()</literal> function, and register
visualization drivers you want directly in your <literal>main()</literal>
function. See <xref linkend="programlist_VisAddExe_3" />.

<example id="programlist_VisAddExe_3">
<title>
An alternative style for the <literal>main()</literal> function.
</title>

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

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

 //----- end of C++ 
</programlisting>
</example>
</para>

<para>
<emphasis>Do not forget</emphasis> 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
<literal>G4VisManager</literal> might have to terminate the graphics system
and/or close the connection.
</para>

<para>
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 <literal>G4VIS_USE</literal> is automatically defined
unless the environment variable <literal>G4VIS_NONE</literal> is set. This
assumes that you are compiling your Geant4 executable with the
standard version of GNUmakefile found in the <literal>config</literal>
directory.
</para>

<para>
<xref linkend="programlist_VisAddExe_4" /> shows an example of the 
<literal>main()</literal> function available for Geant4 Visualization.

<example id="programlist_VisAddExe_4">
<title>
An example of the <literal>main()</literal> function available for 
Geant4 Visualization.
</title>

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

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

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

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

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

      // Event loop
      // Define (G)UI terminal
      G4UIsession * session = new G4UIterminal
      session-&gt;SessionStart();

      delete session;
      delete runManager;

 #ifdef G4VIS_USE
      delete visManager;
 #endif

      return 0;
 }

 //----- end of C++ 
</programlisting>
</example>
</para>

<para>
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:

<informalexample>
<programlisting>
   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.
</programlisting>
</informalexample>
</para>

<para>
For example, in your <literal>main()</literal> function, write the following
code:

<informalexample>
<programlisting>
  ...
  G4VisManager* visManager = new G4VisExecutive ();
  visManager -&gt; SetVerboseLevel (1);
  visManager -&gt; Initialize ();
  ...
</programlisting>
</informalexample>
</para>

<para>
(This can also be set with the <literal>/vis/verbose</literal> command.)
</para>


</sect2>
</sect1>