source: trunk/Documentation/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch08s02.html @ 901

Last change on this file since 901 was 901, checked in by garnier, 16 years ago

Add Geant4 Documentation at 8.12.2008
File size: 17.7 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>8.2.  Adding Visualization to Your Executable</title><link rel="stylesheet" href="../xml/XSLCustomizationLayer/G4HTMLStylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="Geant4 User's Guide for Application Developers"><link rel="up" href="ch08.html" title="Chapter 8.  Visualization"><link rel="prev" href="ch08.html" title="Chapter 8.  Visualization"><link rel="next" href="ch08s03.html" title="8.3.  The Visualization Drivers"><script language="JavaScript">
2function remote_win(fName)
3{
4   var url = "AllResources/Detector/geometry.src/" + fName;
5   RemoteWin=window.open(url,"","resizable=no,toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=0,copyhistory=0,width=520,height=520")
6   RemoteWin.creator=self
7}
8</script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">8.2. 
9Adding Visualization to Your Executable
10</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch08.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><th width="60%" align="center">Chapter 8. 
11Visualization
12</th><td width="20%" align="right"> <a accesskey="n" href="ch08s03.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect.VisAddExe"></a>8.2. 
13Adding Visualization to Your Executable
14</h2></div></div></div><p>
15This section explains how to incorporate your selected
16visualization drivers into the <code class="literal">main()</code> function and create
17an executable for it. In order to perform visualization with your
18Geant4 executable, you must compile it with realized visualization
19driver(s). You may be dazzled by the number of choices of
20visualization driver, but you need not use all of them at one time.
21</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAddExe.InstDrv"></a>8.2.1. 
22Installing Visualization Drivers
23</h3></div></div></div><p>
24Depending on what has been installed on your system, several kinds
25of visualization driver are available. One or many drivers may be
26chosen for realization in compilation, depending on your
27visualization requirements. Features and notes on each driver are
28briefly described in <a href="ch08s03.html" title="8.3. 
29The Visualization Drivers
30">Section 8.3</a>
31"<span class="bold"><strong>Visualization Drivers</strong></span>",
32along with links to detailed web pages for the various drivers.
33</p><p>
34Note that not all drivers can be installed on all systems;
35<a href="ch08s03.html#table.VisDrv_1" title="Table 8.1. 
36Required graphics systems and supported platforms for the various
37visualization drivers.
38">Table 8.1</a> in
39<a href="ch08s03.html" title="8.3. 
40The Visualization Drivers
41">Section 8.3</a> lists all the available drivers
42and the platforms on which they can be installed.
43For any of the visualization drivers to work, the corresponding
44graphics system must be installed beforehand.
45</p><p>
46Unless the environment variable <code class="literal">G4VIS_NONE</code> is set to
47"1", visualization drivers that do not depend on external libraries
48are automatically incorporated into Geant4 libraries during their
49installation. (Here "installation of Geant4 libraries" means the
50generation of Geant4 libraries by compilation.) The automatically
51incorporated visualization drivers are: DAWNFILE, HepRepFile,
52HepRepXML, RayTracer, VRML1FILE, VRML2FILE and ATree and
53GAGTree.
54</p><p>
55The OpenGL, OpenInventor and RayTracerX drivers are not
56incorporated by default. Nor are the DAWN-Network and VRML-Network
57drivers, because they require the network setting of the installed
58machine. In order to incorporate them, the environment variables
59"<code class="literal">G4VIS_BUILD_DRIVERNAME_DRIVER</code>" should be set to
60"<code class="literal">1</code>" before installing the Geant4 libraries:
61
62</p><div class="informalexample"><pre class="programlisting">
63     setenv G4VIS_BUILD_OPENGLX_DRIVER      1  # OpenGL-Xlib driver
64     setenv G4VIS_BUILD_OPENGLXM_DRIVER     1  # OpenGL-Motif driver
65     setenv G4VIS_BUILD_OIX_DRIVER          1  # OpenInventor-Xlib driver
66     setenv G4VIS_BUILD_RAYTRACERX_DRIVER   1  # RayTracer-XLib driver
67     setenv G4VIS_BUILD_DAWN_DRIVER         1  # DAWN-Network driver
68     setenv G4VIS_BUILD_VRML_DRIVER         1  # VRML-Network
69</pre></div><p>
70</p><p>
71Unless the environment variable <code class="literal">G4VIS_NONE</code> is set to "1",
72setting any of the above variables sets a C-pre-processor flag of
73the same name. Also the C-pre-processor flag <code class="literal">G4VIS_BUILD</code>
74is set (see config/G4VIS_BUILD.gmk), which incorparates the
75selected driver into the Geant4 libraries.
76</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAddExe.RealVisDrv"></a>8.2.2. 
77How to Realize Visualization Drivers in an Executable
78</h3></div></div></div><p>
79You can realize and use any of the visualization driver(s) you want
80in your Geant4 executable, provided they are among the set
81installed beforehand into the Geant4 libraries. A warning will
82appear if this is not the case.
83</p><p>
84In order to realize visualization drivers, you must instantiate
85and initialize a subclass of <code class="literal">G4VisManager</code> that implements
86the pure virtual function <code class="literal">RegisterGraphicsSystems()</code>. This
87subclass must be compiled in the user's domain to force the loading
88of appropriate libraries in the right order. The easiest way to do
89this is to use <code class="literal">G4VisExecutive</code>, a provided class with
90included implementation. <code class="literal">G4VisExecutive</code> is sensitive to
91the <code class="literal">G4VIS_USE...</code> variables mentioned below.
92</p><p>
93If you do wish to write your own subclass, you may do so. You
94will see how to do this by looking at <code class="literal">G4VisExecutive.icc</code>.
95A typical extract is:
96
97</p><div class="informalexample"><pre class="programlisting">
98     ...
99       RegisterGraphicsSystem (new G4DAWNFILE);
100     ...
101     #ifdef G4VIS_USE_OPENGLX
102       RegisterGraphicsSystem (new G4OpenGLImmediateX);
103       RegisterGraphicsSystem (new G4OpenGLStoredX);
104     #endif
105     ...
106</pre></div><p>
107</p><p>
108If you wish to use <code class="literal">G4VisExecutive</code> but register an
109additional graphics system, <code class="literal">XXX</code> say, you may do so either
110before or after initializing:
111
112</p><div class="informalexample"><pre class="programlisting">
113     visManager-&gt;RegisterGraphicsSytem(new XXX);
114     visManager-&gt;Initialize();
115</pre></div><p>
116</p><p>
117By default, you get the DAWNFILE, HepRepFile, RayTracer,
118VRML1FILE, VRML2FILE, ATree and GAGTree drivers. Additionally, you
119may choose from the OpenGL-Xlib, OpenGL-Motif, OpenInventor,
120RayTracerX, DAWN-Network and VRML-Network drivers, each of which
121can be selected by setting the proper environment variable:
122
123</p><div class="informalexample"><pre class="programlisting">
124     setenv G4VIS_USE_OPENGLX      1
125     setenv G4VIS_USE_OPENGLXM     1
126     setenv G4VIS_USE_OIX          1
127     setenv G4VIS_USE_RAYTRACERX   1
128     setenv G4VIS_USE_DAWN         1
129     setenv G4VIS_USE_VRML         1
130</pre></div><p>
131</p><p>
132(Of course, this has to be chosen from the set incorporated into
133the Geant4 libraries during their compilation.) Unless the
134environment variable <code class="literal">G4VIS_NONE</code> is set, these set
135C-pre-processor flags of the same name.
136</p><p>
137Also, unless the environment variable <code class="literal">G4VIS_NONE</code> is
138set, the C-pre-processor flag <code class="literal">G4VIS_USE</code> is always set by
139default. This flag is available in describing the <code class="literal">main()</code>
140function.
141</p><p>
142You may have to set additional environment variables for your
143selected visualization drivers and graphics systems. For example,
144the OpenGL driver may require the setting of <code class="literal">OGLHOME</code> which
145points to the location of the OpenGL libraries. For more details,
146see <a href="ch08s03.html" title="8.3. 
147The Visualization Drivers
148">Section 8.3</a> 
149"<span class="bold"><strong>Visualization Drivers</strong></span>" and
150pages linked from there.
151</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAddExe.SampSetup"></a>8.2.3. 
152A Sample Set-up File
153</h3></div></div></div><p>
154The following can be part of the user's <code class="literal">.cshrc</code> or
155<code class="literal">.tcshrc</code> file on a Linux platform to configure the
156environment for creating Geant4 executables available for Geant4
157visualization. This sample is shown only as an example; it may NOT
158correspond to a specific platform configuration and does NOT apply
159in general for any specific setup !
160
161</p><div class="example"><a name="programlist_VisAddExe_1"></a><p class="title"><b>Example 8.1. 
162Part of a sample <code class="literal">.cshrc</code> setup file for the Linux platform.
163</b></p><div class="example-contents"><pre class="programlisting">
164 ############################################################
165 # Main Environment Variables for GEANT4 with Visualization #
166 ############################################################
167
168 ### Platform
169 setenv G4SYSTEM Linux-g++
170
171 ### CLHEP base directory
172 setenv CLHEP_BASE_DIR /opt/local
173
174 ### OpenGL base directory
175 setenv OGLHOME /usr/X11R6
176 
177 ### G4VIS_BUILD
178 ###   Incorporation of OpenGL-Xlib and OpenGL-Motif drivers
179 ###   into Geant4 libraries.
180 setenv G4VIS_BUILD_OPENGLX_DRIVER 1
181 setenv G4VIS_BUILD_OPENGLXM_DRIVER 1
182
183 ### G4VIS_USE
184 ###   Incorporation of OpenGL-Xlib and OpenGL-Motif drivers
185 ###   into Geant4 executables.
186 setenv G4VIS_USE_OPENGLX       1
187 setenv G4VIS_USE_OPENGLXM      1
188
189 ### Viewer for DAWNFILE driver
190 ### Default value is "dawn".  You can change it to, say,
191 ### "david" for volume overlapping tests
192 # setenv G4DAWNFILE_VIEWER david
193
194 ### Viewer for VRMLFILE drivers
195 setenv G4VRMLFILE_VIEWER vrmlview
196
197 ########## end
198</pre></div></div><p><br class="example-break">
199</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAddExe.VisMan"></a>8.2.4. 
200Visualization Manager
201</h3></div></div></div><p>
202Visualization procedures are controlled by the "Visualization
203Manager", a class which must inherit from <span class="emphasis"><em>G4VisManager</em></span>
204defined in the visualization category. Most users will find that
205they can just use the default visualization manager,
206<span class="emphasis"><em>G4VisExecutive</em></span>. The Visualization Manager accepts users'
207requests for visualization, processes them, and passes the
208processed requirements to the abstract interface, i.e., to the
209currently selected visualization driver.
210</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAddExe.WrtMain"></a>8.2.5. 
211How to Write the <code class="literal">main()</code> Function
212</h3></div></div></div><p>
213In order for your Geant4 executable to perform visualization, you
214must instantiate and initialize "your" Visualization Manager in the
215<code class="literal">main()</code> function. The core of the Visualization Manager is
216the class <code class="literal">G4VisManager</code>, defined in the visualization
217category. This class requires that one pure virtual function be
218implemented, namely, <code class="literal">void RegisterGraphicsSystems()</code>. The
219easiest way to do this is to use <code class="literal">G4VisExecutive</code>, as
220described above (but you may write your own class - see above).
221</p><p>
222<a href="ch08s02.html#programlist_VisAddExe_2" title="Example 8.2. 
223The form of the main() function.
224">Example 8.2</a> shows the form of the
225<code class="literal">main()</code> function.
226
227</p><div class="example"><a name="programlist_VisAddExe_2"></a><p class="title"><b>Example 8.2. 
228The form of the <code class="literal">main()</code> function.
229</b></p><div class="example-contents"><pre class="programlisting">
230 //----- C++ source codes: Instantiation and initialization of G4VisManager
231
232 .....
233 // Your Visualization Manager
234 #include "G4VisExecutive.hh"
235 .....
236
237 // Instantiation and initialization of the Visualization Manager
238 #ifdef G4VIS_USE
239 G4VisManager* visManager = new G4VisExecutive;
240 visManager -&gt; initialize ();
241 #endif
242
243 .....
244 #ifdef G4VIS_USE
245 delete visManager;
246 #endif
247
248 //----- end of C++
249</pre></div></div><p><br class="example-break">
250</p><p>
251Alternatively, you can implement an empty
252<code class="literal">RegisterGraphicsSystems()</code> function, and register
253visualization drivers you want directly in your <code class="literal">main()</code>
254function. See <a href="ch08s02.html#programlist_VisAddExe_3" title="Example 8.3. 
255An alternative style for the main() function.
256">Example 8.3</a>.
257
258</p><div class="example"><a name="programlist_VisAddExe_3"></a><p class="title"><b>Example 8.3. 
259An alternative style for the <code class="literal">main()</code> function.
260</b></p><div class="example-contents"><pre class="programlisting">
261 //----- C++ source codes: How to register a visualization driver directly
262 //                        in main() function
263
264 .....
265 G4VisManager* visManager = new G4VisExecutive;
266 visManager -&gt; RegisterGraphicsSystem (new MyGraphicsSystem);
267 .....
268 delete visManager
269
270 //----- end of C++
271</pre></div></div><p><br class="example-break">
272</p><p>
273<span class="emphasis"><em>Do not forget</em></span> to delete the instantiated Visualization
274Manager by yourself. Note that a graphics system for Geant4 Visualization
275may run as a different process. In that case, the destructor of
276<code class="literal">G4VisManager</code> might have to terminate the graphics system
277and/or close the connection.
278</p><p>
279We recommend that the instantiation, initialization, and
280deletion of the Visualization Manager be protected by
281C-pre-processor commands, as in the novice examples. The
282C-pre-processor macro <code class="literal">G4VIS_USE</code> is automatically defined
283unless the environment variable <code class="literal">G4VIS_NONE</code> is set. This
284assumes that you are compiling your Geant4 executable with the
285standard version of GNUmakefile found in the <code class="literal">config</code>
286directory.
287</p><p>
288<a href="ch08s02.html#programlist_VisAddExe_4" title="Example 8.4. 
289An example of the main() function available for
290Geant4 Visualization.
291">Example 8.4</a> shows an example of the
292<code class="literal">main()</code> function available for Geant4 Visualization.
293
294</p><div class="example"><a name="programlist_VisAddExe_4"></a><p class="title"><b>Example 8.4. 
295An example of the <code class="literal">main()</code> function available for
296Geant4 Visualization.
297</b></p><div class="example-contents"><pre class="programlisting">
298 //----- C++ source codes: An example of main() for visualization
299 .....
300 #include "G4VisExecutive.hh"
301 .....
302
303 int main()
304 {
305      // Run Manager
306      G4RunManager * runManager = new G4RunManager;
307
308      // Detector components
309      runManager-&gt;set_userInitialization(new MyDetectorConstruction);
310      runManager-&gt;set_userInitialization(new MyPhysicsList);
311
312      // UserAction classes.
313      runManager-&gt;set_userAction(new MyRunAction);
314      runManager-&gt;set_userAction(new MyPrimaryGeneratorAction);
315      runManager-&gt;set_userAction(new MyEventAction);
316      runManager-&gt;set_userAction(new MySteppingAction);
317
318 #ifdef G4VIS_USE
319      G4VisManager* visManager = new G4VisExecutive;
320      visManager -&gt; initialize ();
321 #endif
322
323      // Event loop
324      // Define (G)UI terminal
325      G4UIsession * session = new G4UIterminal
326      session-&gt;sessionStart();
327
328      delete session;
329      delete runManager;
330
331 #ifdef G4VIS_USE
332      delete visManager;
333 #endif
334
335      return 0;
336 }
337
338 //----- end of C++
339</pre></div></div><p><br class="example-break">
340</p><p>
341Useful information on incorporated visualization drivers can be
342displayed in initializing the Visualization Manager. This is done
343by setting the verbosity flag to an appropriate string:
344
345</p><div class="informalexample"><pre class="programlisting">
346   Simple graded message scheme - give first letter or a digit:
347    0) quiet,         // Nothing is printed.
348    1) startup,       // Startup and endup messages are printed...
349    2) errors,        // ...and errors...
350    3) warnings,      // ...and warnings...
351    4) confirmations, // ...and confirming messages...
352    5) parameters,    // ...and parameters of scenes and views...
353    6) all            // ...and everything available.
354</pre></div><p>
355</p><p>
356For example, in your <code class="literal">main()</code> function, write the following
357code:
358
359</p><div class="informalexample"><pre class="programlisting">
360  ...
361  G4VisManager* visManager = new G4VisExecutive ();
362  visManager -&gt; SetVerboseLevel (1);
363  visManager -&gt; Initialize ();
364  ...
365</pre></div><p>
366</p><p>
367(This can also be set with the <code class="literal">/vis/verbose</code> command.)
368</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch08.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html"><img src="AllResources/IconsGIF/up.gif" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch08s03.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. 
369Visualization
370 </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="AllResources/IconsGIF/home.gif" alt="Home"></a></td><td width="40%" align="right" valign="top"> 8.3. 
371The Visualization Drivers
372</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.