source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/Visualization/visexecutable.html @ 1231

Last change on this file since 1231 was 1208, checked in by garnier, 15 years ago

CVS update
File size: 13.4 KB
Line 
1<HTML>
2<TITLE>Adding Visualization to Your Executable
3</TITLE>
4<BODY>
5
6<TABLE WIDTH="100%" >
7<TR>
8<TD>
9</A>
10<A HREF="index.html">
11<IMG SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents" HEIGHT=16 WIDTH=59></A>
12<A HREF="introduction.html">
13<IMG SRC="../../../../resources/html/IconsGIF/Previous.gif" ALT="Previous" HEIGHT=16 WIDTH=59></A>
14<a href="visdrivers.html">
15<IMG SRC="../../../../resources/html/IconsGIF/Next.gif" ALT="Next" HEIGHT=16 WIDTH=59></a>
16</TD>
17
18<TD ALIGN="Right"><FONT COLOR="#238E23"><FONT SIZE=-1>
19<B>Geant4 User's Guide</B> <BR>
20<B>For Application Developers</B> <BR>
21<B>Visualization</B> </FONT></FONT> </TD>
22</TR>
23</TABLE>
24
25<CENTER><FONT COLOR="#238E23"><FONT SIZE=+3>
26<b>8.2 Adding Visualization to Your Executable</b><BR>
27</FONT></FONT></CENTER>
28<BR>
29
30<HR ALIGN="Center" SIZE="7%"><BR>
31
32 This section explains how to incorporate your selected visualization drivers
33 into the <tt>main()</tt> function and create an executable for it.  In order
34 to perform visualization with your Geant4 executable, you must compile it
35 with realized visualization driver(s). You may be dazzled by the number of
36 choices of visualization driver, but you need not use all of them at one time.
37 
38<h4>8.2.1 Installing Visualization Drivers</h4>
39
40 Depending on what has been installed on your system, several kinds of
41 visualization driver are available. One or many drivers may be chosen for
42 realization in compilation, depending on your visualization requirements.
43 Features and notes on each driver are briefly described in
44 <a href="visdrivers.html">Section 8.3</a> "<b>Visualization Drivers</b>",
45 along with links to detailed web pages for the various drivers.
46<P>
47 Note that not all drivers can be installed on all systems;
48 Table 8.1 in <a href="visdrivers.html">Section 8.3</a> lists all the available
49 drivers and the platforms on which they can be installed. For any of the
50 visualization drivers to work, the corresponding graphics system must be
51 installed beforehand.
52<P>
53Unless the environment variable <tt>G4VIS_NONE</tt> is set to "1",
54visualization drivers that do not depend on external libraries are
55automatically incorporated into Geant4 libraries during their installation.
56(Here "installation of Geant4 libraries" means the generation of Geant4
57libraries by compilation.)
58The automatically incorporated visualization drivers are:
59DAWNFILE, HepRepFile, HepRepXML, RayTracer, VRML1FILE, VRML2FILE and ATree and GAGTree.
60<P>
61The OpenGL, OpenInventor and RayTracerX drivers are not incorporated by default.
62Nor are the DAWN-Network and VRML-Network drivers, because they require the
63network setting of the installed machine.  In order to incorporate them,
64the environment variables "<TT>G4VIS_BUILD_DRIVERNAME_DRIVER</TT>" should be
65set to  "<tt>1</tt>" before installing the Geant4 libraries:
66<PRE>
67     setenv G4VIS_BUILD_OPENGLX_DRIVER      1  # OpenGL-Xlib driver
68     setenv G4VIS_BUILD_OPENGLXM_DRIVER     1  # OpenGL-Motif driver
69     setenv G4VIS_BUILD_OIX_DRIVER          1  # OpenInventor-Xlib driver
70     setenv G4VIS_BUILD_RAYTRACERX_DRIVER   1  # RayTracer-XLib driver
71     setenv G4VIS_BUILD_DAWN_DRIVER         1  # DAWN-Network driver
72     setenv G4VIS_BUILD_VRML_DRIVER         1  # VRML-Network
73</PRE>
74Unless the environment variable <TT>G4VIS_NONE</TT> is set to "1",
75setting any of the above variables sets a C-pre-processor flag of the same
76name. Also the C-pre-processor flag <TT>G4VIS_BUILD </TT> is set (see
77config/G4VIS_BUILD.gmk), which incorparates the selected driver into the
78Geant4 libraries.
79
80<h4>8.2.2 How to Realize Visualization Drivers in an Executable</h4>
81
82 You can realize and use any of the visualization driver(s) you want
83 in your Geant4 executable, provided they are among the set installed
84 beforehand into the Geant4 libraries. A warning will appear if this is
85 not the case.
86
87 <P>In order to realize visualization drivers, you must instantiate
88 and initialize a subclass of <tt>G4VisManager</tt> that implements
89 the pure virtual function <tt>RegisterGraphicsSystems()</tt>.  This
90 subclass must be compiled in the user's domain to force the loading
91 of appropriate libraries in the right order.  The easiest way to do
92 this is to use <tt>G4VisExecutive</tt>, a provided class with
93 included implementation.  <tt>G4VisExecutive</tt> is sensitive to the
94 <tt>G4VIS_USE...</tt> variables mentioned below.
95
96<P>If you do wish to write your own subclass, you may do so.  You will
97see how to do this by looking at <tt>G4VisExecutive.icc</tt>.  A
98typical extract is:
99
100<PRE>
101     ...
102       RegisterGraphicsSystem (new G4DAWNFILE);
103     ...
104     #ifdef G4VIS_USE_OPENGLX
105       RegisterGraphicsSystem (new G4OpenGLImmediateX);
106       RegisterGraphicsSystem (new G4OpenGLStoredX);
107     #endif
108     ...
109</PRE>
110<P>If you wish to use <tt>G4VisExecutive</tt> but register an
111additional graphics system, <tt>XXX</tt> say, you may do so either
112before or after initializing:
113<PRE>
114     visManager->RegisterGraphicsSytem(new XXX);
115     visManager->Initialize();
116</PRE>
117<P>
118Source listing 8.2.2<BR>
119An example of a typical <tt>main()</tt> function is given below.
120<P>
121By default, you get the DAWNFILE, HepRepFile, RayTracer, VRML1FILE, VRML2FILE, ATree and
122GAGTree drivers. Additionally, you may choose from the OpenGL-Xlib, OpenGL-Motif, OpenInventor,
123RayTracerX, DAWN-Network and VRML-Network drivers, each of
124which can be selected by setting the proper environment variable:
125<PRE>
126     setenv G4VIS_USE_OPENGLX      1
127     setenv G4VIS_USE_OPENGLXM     1
128     setenv G4VIS_USE_OIX          1
129     setenv G4VIS_USE_RAYTRACERX   1
130     setenv G4VIS_USE_DAWN         1
131     setenv G4VIS_USE_VRML         1
132</PRE>
133<P>
134(Of course, this has to be chosen from the set incorporated into
135the Geant4 libraries during their compilation.)
136Unless the environment variable <TT>G4VIS_NONE</TT> is set,
137these set C-pre-processor flags of the same name.
138<P>
139Also, unless the environment variable <TT>G4VIS_NONE</TT> is set, the
140C-pre-processor flag <TT>G4VIS_USE</TT> is always set by default.
141This flag is available in describing the <tt>main()</tt> function.
142
143<P>
144 You may have to set additional environment variables for your selected
145 visualization drivers and graphics systems.
146 For example, the OpenGL driver may require the setting of <tt>OGLHOME</tt>
147 which points to the location of the OpenGL libraries.  For more details,
148 see <a href="visdrivers.html">Section 8.3</a> "<b>Visualization Drivers</b>"
149 and pages linked from there.
150<P>
151
152<h4>A Sample Set-up File </h4>
153 The following can be part of the user's <tt>.cshrc</tt> or <tt>.tcshrc</tt> 
154 file on a Linux platform to configure the environment for creating Geant4
155 executables available for Geant4 visualization. This sample is shown only as
156 an example; it may NOT correspond to a specific platform configuration and
157 does NOT apply in general for any specific setup !
158<P>
159<center>
160<table border=2 cellpadding=10>
161<tr>
162<td>
163<PRE>
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>
199</td>
200</tr>
201<tr>
202<td align=center>
203Source listing 8.2.1<BR>
204 Part of a sample <tt>.cshrc</tt> setup file for the Linux platform.
205</td>
206</tr>
207</table></center>
208
209
210 <h4>8.2.3 Visualization Manager</h4>
211 Visualization procedures are controlled by the "Visualization Manager",
212 a class which must inherit from  <i>G4VisManager</i> defined in the visualization category.
213 Most users will find that they can just use the default visualization manager, <i>G4VisExecutive</i>.
214 The Visualization Manager accepts users' requests for visualization, processes them, and passes
215 the processed requirements to the abstract interface, i.e., to the currently
216 selected visualization driver.
217
218<h4>8.2.4 How to Write the <tt>main()</tt> Function</h4>
219
220 In order for your Geant4 executable to perform visualization, you
221 must instantiate and initialize "your" Visualization Manager in the
222 <tt>main()</tt> function. The core of the Visualization Manager is
223 the class <tt>G4VisManager</tt>, defined in the visualization
224 category.  This class requires that one pure virtual function be
225 implemented, namely, <tt>void RegisterGraphicsSystems()</tt>.  The
226 easiest way to do this is to use <tt>G4VisExecutive</tt>, as
227 described above (but you may write your own class - see above).
228
229<P>
230 Source listing 8.2.2 shows the form of the <tt>main()</tt> function.
231<p>
232<center>
233<table border=2 cellpadding=10>
234<tr>
235<td>
236<PRE>
237 //----- C++ source codes: Instantiation and initialization of G4VisManager
238
239 .....
240 // Your Visualization Manager
241 #include "G4VisExecutive.hh"
242 .....
243
244 // Instantiation and initialization of the Visualization Manager
245 #ifdef G4VIS_USE
246 G4VisManager* visManager = new G4VisExecutive;
247 visManager -> initialize ();
248 #endif
249
250 .....
251 #ifdef G4VIS_USE
252 delete visManager;
253 #endif
254
255 //----- end of C++
256</PRE>
257</td>
258</tr>
259<tr>
260<td align=center>
261 Source listing 8.2.2<BR>
262 The form of the <tt>main()</tt> function.
263</td>
264</tr>
265</table></center>
266<P>
267 Alternatively, you can implement an empty <tt>RegisterGraphicsSystems()</tt> 
268 function, and register visualization drivers you want directly in
269 your <tt>main()</tt> function. See Source listing 8.2.3.
270<p>
271<center>
272<table border=2 cellpadding=10>
273<tr>
274<td>
275<PRE>
276 //----- C++ source codes: How to register a visualization driver directly
277 //                        in main() function
278
279 .....
280 G4VisManager* visManager = new G4VisExecutive;
281 visManager -> RegisterGraphicsSystem (new MyGraphicsSystem);
282 .....
283 delete visManager
284
285 //----- end of C++
286</PRE>
287</td>
288</tr>
289<tr>
290<td align=center>
291 Source listing 8.2.3<BR>
292 An alternative style for the <tt>main()</tt> function.
293</td>
294</tr>
295</table></center>
296<P>
297 DO NOT FORGET to delete the instantiated Visualization Manager by yourself.
298 Note that a graphics system for Geant4 Visualization may run as a different
299 process. In that case, the destructor of <tt>G4VisManager</tt> might have to
300 terminate the graphics system and/or close the connection.
301<P>
302 We recommend that the instantiation, initialization, and deletion of the
303 Visualization Manager be protected by C-pre-processor commands, as in the
304 novice examples.  The C-pre-processor macro <TT>G4VIS_USE</TT> is
305 automatically defined unless the environment variable <TT>G4VIS_NONE</TT> is
306 set.  This assumes that you are compiling your Geant4 executable with the
307 standard version of GNUmakefile found in the <TT>config</TT> directory.
308<P>
309 Source listing 8.2.4 shows an example of the <tt>main()</tt> function
310 available for Geant4 Visualization.
311<p>
312<center>
313<table border=2 cellpadding=10>
314<tr>
315<td>
316<PRE>
317 //----- C++ source codes: An example of main() for visualization
318 .....
319 #include "G4VisExecutive.hh"
320 .....
321
322 int main()
323 {
324      // Run Manager
325      G4RunManager * runManager = new G4RunManager;
326
327      // Detector components
328      runManager->set_userInitialization(new MyDetectorConstruction);
329      runManager->set_userInitialization(new MyPhysicsList);
330
331      // UserAction classes.
332      runManager->set_userAction(new MyRunAction);
333      runManager->set_userAction(new MyPrimaryGeneratorAction);
334      runManager->set_userAction(new MyEventAction);
335      runManager->set_userAction(new MySteppingAction);
336
337 #ifdef G4VIS_USE
338      G4VisManager* visManager = new G4VisExecutive;
339      visManager -> initialize ();
340 #endif
341
342      // Event loop
343      // Define (G)UI terminal
344      G4UIsession * session = new G4UIterminal
345      session->sessionStart();
346
347      delete session;
348      delete runManager;
349
350 #ifdef G4VIS_USE
351      delete visManager;
352 #endif
353
354      return 0;
355 }
356
357 //----- end of C++
358</PRE>
359</td>
360</tr>
361<tr>
362<td align=center>
363 Source listing 8.2.4<BR>
364 An example of the <tt>main()</tt> function available for Geant4 Visualization.
365</td>
366</tr>
367</table></center>
368<P>
369 Useful information on incorporated visualization drivers can be displayed
370 in initializing the Visualization Manager. This is done by setting the
371 verbosity flag to an appropriate string:
372<PRE>
373   Simple graded message scheme - give first letter or a digit:
374    0) quiet,         // Nothing is printed.
375    1) startup,       // Startup and endup messages are printed...
376    2) errors,        // ...and errors...
377    3) warnings,      // ...and warnings...
378    4) confirmations, // ...and confirming messages...
379    5) parameters,    // ...and parameters of scenes and views...
380    6) all            // ...and everything available.
381</PRE>
382For example, in your
383 <tt>main()</tt> function, write the following code:
384<PRE>
385  ...
386  G4VisManager* visManager = new G4VisExecutive ();
387  visManager -> SetVerboseLevel (1);
388  visManager -> Initialize ();
389  ...
390</PRE>
391(This can also be set with the <tt>/vis/verbose</tt> command.)
392<P>
393
394<HR>
395 <A HREF="visdrivers.html">Next section</A><BR>
396 <A HREF="introduction.html">Back to contents</A>
397</BODY>
398</HTML>
Note: See TracBrowser for help on using the repository browser.