[1208] | 1 | \newcommand{\Gfour}{{\sc Geant4}\xspace} |
---|
| 2 | \newcommand{\GI}{Graphics Interface\xspace} |
---|
| 3 | \newcommand{\GVS}{\Gfour Visualisation System\xspace} |
---|
| 4 | \newcommand{\GVM}{\Gfour Visualisation Manager\xspace} |
---|
| 5 | \newcommand{\gd}{graphics driver\xspace} |
---|
| 6 | \newcommand{\gds}{graphics drivers\xspace} |
---|
| 7 | \newcommand{\gs}{graphics system\xspace} |
---|
| 8 | \newcommand{\gss}{graphics systems\xspace} |
---|
| 9 | \newcommand{\vs}{visualisation system\xspace} |
---|
| 10 | \newcommand{\vm}{visualisation manager\xspace} |
---|
| 11 | \newcommand{\UGA}{User Guide for Application Developers\xspace} |
---|
| 12 | \newcommand{\UGT}{User Guide for Toolkit Developers\xspace} |
---|
| 13 | \newcommand{\SRM}{Software Reference Manual\xspace} |
---|
| 14 | |
---|
| 15 | \chapter{Visualisation} |
---|
| 16 | \label{ExtendChapVis} |
---|
| 17 | |
---|
| 18 | This Chapter is intended to be read after Chapter \ref{OOChapVis} on |
---|
| 19 | Visualisation object oriented design in Part II. Many of the concepts |
---|
| 20 | used here are defined there, and it strongly recommended that a writer |
---|
| 21 | of a new visualisation driver or trajectory drawer reads Chapter |
---|
| 22 | \ref{OOChapVis} first. The class structure described there is |
---|
| 23 | summarised in the Figure \ref{VisClassDiagram}. |
---|
| 24 | |
---|
| 25 | \begin{figure} |
---|
| 26 | \begin{center} |
---|
| 27 | \includegraphics[width=\linewidth]{GuideToExtendFunctionality/Visualization/visClassDiagram.eps} |
---|
| 28 | \caption{Geant Visualisation System Class Diagram} |
---|
| 29 | \label{VisClassDiagram} |
---|
| 30 | \end{center} |
---|
| 31 | \end{figure} |
---|
| 32 | |
---|
| 33 | \section{Creating a new \gd} |
---|
| 34 | |
---|
| 35 | To create a new \gd for {\sc Geant4}, it is necessary to implement a |
---|
| 36 | new set of three classes derived from the three base classes, {\tt |
---|
| 37 | G4VGraphicsSystem}, {\tt G4VSceneHandler} and {\tt G4VViewer}. |
---|
| 38 | |
---|
| 39 | \subsection{A useful place to start} |
---|
| 40 | |
---|
| 41 | A skeleton set of classes is included in the code distribution in the |
---|
| 42 | visualisation category under subdirectory {\tt visualisation/XXX} (but |
---|
| 43 | they are not default-registered graphics systems\footnote{To do this, |
---|
| 44 | simply instantiate and register, for example: {\tt |
---|
| 45 | visManager->\-RegisterGraphicsSystem(new G4XXX)} before {\tt |
---|
| 46 | visManager->Initialise()}.}). There are several sets of classes, |
---|
| 47 | described in more detail below. A recommended approach is to copy the |
---|
| 48 | files that best match your \gs to a new subdirectory with a name that |
---|
| 49 | suits your \gs. Then |
---|
| 50 | \begin{enumerate} |
---|
| 51 | \item Change the name of the files (change the code -- {\tt XXX} or |
---|
| 52 | {\tt XXXFile}, etc., as chosen -- to something that suits your \gs). |
---|
| 53 | \item Change {\tt XXX} similarly in all files. |
---|
| 54 | \item Change {\tt XXX} similarly in {\tt name := G4XXX} in {\tt GNUmakefile}. |
---|
| 55 | \item Add your new subdirectory to {\tt SUBDIRS} and {\tt SUBLIBS} in |
---|
| 56 | {\tt visualisation/GNUmakefile}. |
---|
| 57 | \item Look at the code and use it to build your visualisation |
---|
| 58 | driver. You might also find it useful to look at {\tt ASCIITree} (and |
---|
| 59 | {\tt VTree}) as an example of a minimal \gd. Look at |
---|
| 60 | {\tt FukuiRenderer} as an example of a driver which implements {\tt AddSolid} |
---|
| 61 | methods for some solids. Look at {\tt OpenGL} as an example of a driver |
---|
| 62 | which implements a graphical database (display lists) and the |
---|
| 63 | machinery to decide when to rebuild. (OpenGL is complicated by the |
---|
| 64 | proliferation of combinations of the use or not of display lists for |
---|
| 65 | three window systems, X-windows, X with motif (interactive), Microsoft |
---|
| 66 | Windows (Win32), a total of six combinations, and much use is made of |
---|
| 67 | inheritance to avoid code duplication.) |
---|
| 68 | \item If it requires external libraries, introduce two new environment |
---|
| 69 | variables {\tt G4VIS\_BUILD\_XXX\_DRIVER} and {\tt G4VIS\_USE\_XXX} |
---|
| 70 | (where {\tt XXX} is your choice as above) and make the modifications to: |
---|
| 71 | \begin{itemize} |
---|
| 72 | \item {\tt source/visualization/management/include/G4VisExecutive.icc} |
---|
| 73 | \item {\tt config/G4VIS\_BUILD.gmk} |
---|
| 74 | \item {\tt config/G4VIS\_USE.gmk} |
---|
| 75 | \end{itemize} |
---|
| 76 | \end{enumerate} |
---|
| 77 | |
---|
| 78 | \subsubsection{Graphics driver templates in the {\tt XXX} sub-category} |
---|
| 79 | \label{XXXsub} |
---|
| 80 | |
---|
| 81 | You may use the following templates to help you get started writing a |
---|
| 82 | \gd. (The word ``template'' is used in the ordinary sense of the |
---|
| 83 | word; they are not C++ templates.) |
---|
| 84 | |
---|
| 85 | \begin{itemize} |
---|
| 86 | |
---|
| 87 | \item{\tt G4XXX, G4XXXSceneHandler, G4XXXViewer} Templates for the |
---|
| 88 | simplest possible \gd. These would be suitable for an ``immediate'' |
---|
| 89 | driver, i.e., one which renders each object immediately to a screen. |
---|
| 90 | Of course, if the view needs re-drawing, as, for example, after a |
---|
| 91 | change of viewpoint, the viewer requests a re-issue of drawn |
---|
| 92 | objects. |
---|
| 93 | |
---|
| 94 | \item{\tt G4XXXFile, G4XXXFileSceneHandler, G4XXXFileViewer} Templates |
---|
| 95 | for a file-writing graphics driver. The particular features are: |
---|
| 96 | delayed opening of the file on receipt of the first item; rewinding |
---|
| 97 | file on ClearView (to simulate the clearing of views and prevent the |
---|
| 98 | duplication of material in the file); closing of the file on ShowView, |
---|
| 99 | which may also trigger the launch of a browser. There are various |
---|
| 100 | degrees of sophistication in, for example, the allocation of filenames |
---|
| 101 | -- see {\tt FukuiRenderer} or {\tt HepRepFile}. |
---|
| 102 | |
---|
| 103 | These templates also show the use of a specific {\tt AddSolid} function |
---|
| 104 | whereby the specific parameters, for example, the dimensions of a {\tt |
---|
| 105 | G4Box}, can be accessed. |
---|
| 106 | |
---|
| 107 | \item{\tt G4XXXStored, G4XXXStoredSceneHandler, G4XXXStoredViewer} |
---|
| 108 | Templates for a graphics driver with a store/database. The advantage |
---|
| 109 | of a store is that the view can be refreshed, for example, from a |
---|
| 110 | different viewpoint, without a need to recompute. It is up to the |
---|
| 111 | viewer to decide when a re-computation is necessary. They also show how |
---|
| 112 | to distinguish between permanent and transient objects -- see also |
---|
| 113 | Section \ref{Transients}. |
---|
| 114 | |
---|
| 115 | \item{\tt G4XXXSG, G4XXXSGSceneHandler, G4XXXSGViewer} Templates for a |
---|
| 116 | sophisticated \gd with a scene graph. The scene graph, following Open |
---|
| 117 | Inventor parlance, is a tree of objects that dictates the order in |
---|
| 118 | which the objects are rendered. It obviously lends itself to the |
---|
| 119 | rendering of the \Gfour geometry hierarchy. For example, the Open |
---|
| 120 | Inventor driver draws only the top level volumes unless made invisible |
---|
| 121 | by picking. Thus the user can unwrap a branch of the geometry level |
---|
| 122 | by level. This has performance benefits and gives the user significant |
---|
| 123 | and useful control over the view. These classes show how to make a |
---|
| 124 | scene graph of {\em drawn} volumes, i.e., the set of volumes that have |
---|
| 125 | not been culled. (Normally, volumes marked invisible are culled, |
---|
| 126 | i.e., not drawn. Also, the user may wish to limit the number of drawn |
---|
| 127 | volumes for performance reasons.) The drivers also have to process |
---|
| 128 | non-geometry items and distinguish between transient and permanent |
---|
| 129 | objects as above. |
---|
| 130 | \end{itemize} |
---|
| 131 | |
---|
| 132 | \subsection{Important Command Actions} |
---|
| 133 | \label{Actions} |
---|
| 134 | |
---|
| 135 | To help understand how the \GVS works, here are a few important |
---|
| 136 | function invocation sequences that follow user commands. For an |
---|
| 137 | explanation of the commands themselves, see command guidance or the |
---|
| 138 | Control section of the Application Developers Guide. For a |
---|
| 139 | fuller explanation of the functions, see appropriate base class head |
---|
| 140 | files or Software Reference Manual. |
---|
| 141 | |
---|
| 142 | \begin{itemize} |
---|
| 143 | |
---|
| 144 | \item{\tt /vis/viewer/clear} |
---|
| 145 | \begin{verbatim} |
---|
| 146 | viewer->ClearView(); // Clears buffer or rewinds file. |
---|
| 147 | viewer->FinishView(); // Swaps buffer (double buffer systems). |
---|
| 148 | \end{verbatim} |
---|
| 149 | |
---|
| 150 | \item{\tt /vis/viewer/flush} |
---|
| 151 | \begin{verbatim} |
---|
| 152 | /vis/viewer/refresh |
---|
| 153 | /vis/viewer/update |
---|
| 154 | \end{verbatim} |
---|
| 155 | |
---|
| 156 | \item{\tt /vis/viewer/rebuild} |
---|
| 157 | \begin{verbatim} |
---|
| 158 | viewer->SetNeedKernelVisit(true); |
---|
| 159 | \end{verbatim} |
---|
| 160 | |
---|
| 161 | \item{\tt /vis/viewer/refresh} If the view is ``auto-refresh'', this |
---|
| 162 | command is also invoked after {\tt /vis/viewer/create}, {\tt |
---|
| 163 | /vis/viewer/rebuild} or a change of view parameters ({\tt |
---|
| 164 | /vis/viewer/set/}..., etc.). |
---|
| 165 | \begin{verbatim} |
---|
| 166 | viewer->SetView(); // Sets camera position, etc. |
---|
| 167 | viewer->ClearView(); // Clears buffer or rewinds file. |
---|
| 168 | viewer->DrawView(); // Draws to screen or writes to |
---|
| 169 | // file/socket. |
---|
| 170 | \end{verbatim} |
---|
| 171 | |
---|
| 172 | \item{\tt /vis/viewer/update} |
---|
| 173 | \begin{verbatim} |
---|
| 174 | viewer->ShowView(); // Activates interactive windows or |
---|
| 175 | // closes file and/or triggers |
---|
| 176 | // post-processing. |
---|
| 177 | \end{verbatim} |
---|
| 178 | |
---|
| 179 | \item{\tt /vis/scene/notifyHandlers} For each viewer of the current |
---|
| 180 | scene, the equivalent of |
---|
| 181 | \begin{verbatim} |
---|
| 182 | /vis/viewer/refresh |
---|
| 183 | \end{verbatim} |
---|
| 184 | If ``flush'' is specified on the command line, the equivalent of |
---|
| 185 | \begin{verbatim} |
---|
| 186 | /vis/viewer/update |
---|
| 187 | \end{verbatim} |
---|
| 188 | {\tt /vis/scene/notifyHandlers} is also invoked after a change |
---|
| 189 | of scene ({\tt /vis/scene/add/}..., etc.). |
---|
| 190 | |
---|
| 191 | \end{itemize} |
---|
| 192 | |
---|
| 193 | \subsection{What happens in {\tt DrawView}?} |
---|
| 194 | \label{DrawView} |
---|
| 195 | |
---|
| 196 | This depends on the viewer. Those with their own graphical database, |
---|
| 197 | for example, OpenGL's display lists or Open Inventor's scene graph, do |
---|
| 198 | not need to re-traverse the scene unless there has been a significant |
---|
| 199 | change of view parameters. For example, a mere change of viewpoint |
---|
| 200 | requires only a change of model-view matrix whilst a change of |
---|
| 201 | rendering mode from wireframe to surface might require a rebuild of |
---|
| 202 | the graphical database. A rebuild of the run-duration (persistent) |
---|
| 203 | objects in the scene is called a ``kernel visit''; the viewer prints |
---|
| 204 | ``Traversing scene data...''. |
---|
| 205 | |
---|
| 206 | Note that end-of-event (transient) objects are only rebuilt at the end |
---|
| 207 | of an event or run, under control of the visualisation manager. Smart |
---|
| 208 | scene handlers keep them in separate display lists so that they can be |
---|
| 209 | rebuilt separately from the run-duration objects - see Section |
---|
| 210 | \ref{Transients}. |
---|
| 211 | |
---|
| 212 | \begin{itemize} |
---|
| 213 | |
---|
| 214 | \item{\bf Integrated viewers with no graphical database} For example, |
---|
| 215 | G4OpenGLImmediateXViewer::DrawView(). |
---|
| 216 | \begin{verbatim} |
---|
| 217 | NeedKernelVisit(); // Always need to visit G4 kernel. |
---|
| 218 | ProcessView(); |
---|
| 219 | FinishView(); |
---|
| 220 | \end{verbatim} |
---|
| 221 | |
---|
| 222 | \item{\bf Integrated viewers with graphical database} For example,\\ |
---|
| 223 | G4OpenGLStoredXViewer::DrawView(). |
---|
| 224 | \begin{verbatim} |
---|
| 225 | KernelVisitDecision(); // Private function containing... |
---|
| 226 | if significant change of view parameters... |
---|
| 227 | NeedKernelVisit(); |
---|
| 228 | ProcessView(); |
---|
| 229 | FinishView(); |
---|
| 230 | \end{verbatim} |
---|
| 231 | |
---|
| 232 | \item{\bf File-writing viewers} For example, G4DAWNFILEViewer::DrawView(). |
---|
| 233 | \begin{verbatim} |
---|
| 234 | NeedKernelVisit(); |
---|
| 235 | ProcessView(); |
---|
| 236 | \end{verbatim} |
---|
| 237 | |
---|
| 238 | Note that viewers needing to invoke {\tt FinishView} must do it in |
---|
| 239 | {\tt DrawView}. |
---|
| 240 | |
---|
| 241 | \end{itemize} |
---|
| 242 | |
---|
| 243 | \subsection{What happens in {\tt ProcessView}?} |
---|
| 244 | |
---|
| 245 | {\tt ProcessView} is inherited from {\tt G4VViewer}: |
---|
| 246 | |
---|
| 247 | \begin{verbatim} |
---|
| 248 | void G4VViewer::ProcessView() { |
---|
| 249 | // If ClearStore has been requested, e.g., if the scene has changed, |
---|
| 250 | // of if the concrete viewer has decided that it necessary to visit |
---|
| 251 | // the kernel, perhaps because the view parameters have changed |
---|
| 252 | // drastically (this should be done in the concrete viewer's |
---|
| 253 | // DrawView)... |
---|
| 254 | if (fNeedKernelVisit) { |
---|
| 255 | fSceneHandler.ProcessScene(*this); |
---|
| 256 | fNeedKernelVisit = false; |
---|
| 257 | } |
---|
| 258 | } |
---|
| 259 | \end{verbatim} |
---|
| 260 | |
---|
| 261 | \subsection{What happens in {\tt ProcessScene}?} |
---|
| 262 | \label{ProcessScene} |
---|
| 263 | |
---|
| 264 | ProcessScene is inherited from {\tt G4VSceneHandler}. It causes a |
---|
| 265 | traversal of the run-duration models in the scene. For drivers with |
---|
| 266 | graphical databases, it causes a rebuild ({\tt ClearStore}). Then for |
---|
| 267 | the run-duration models: |
---|
| 268 | \begin{verbatim} |
---|
| 269 | fReadyForTransients = false; |
---|
| 270 | BeginModeling(); |
---|
| 271 | for each run-duration model... |
---|
| 272 | pModel -> DescribeYourselfTo(*this); |
---|
| 273 | EndModeling(); |
---|
| 274 | fReadyForTransients = true; |
---|
| 275 | \end{verbatim} |
---|
| 276 | (A second pass is made on request -- see {\tt |
---|
| 277 | G4VSceneHandler::ProcessScene}.) The use of {\tt fReadyForTransients} |
---|
| 278 | is described in Section \ref{Transients}. |
---|
| 279 | |
---|
| 280 | What happens then depends on the type of model: |
---|
| 281 | |
---|
| 282 | \begin{itemize} |
---|
| 283 | |
---|
| 284 | \item{\tt G4AxesModel} {\tt G4AxesModel::DescribeYourselfTo} simply calls |
---|
| 285 | sceneHandler.AddPrimitive methods directly. |
---|
| 286 | \begin{verbatim} |
---|
| 287 | sceneHandler.BeginPrimitives(); |
---|
| 288 | sceneHandler.AddPrimitive(x_axis); // etc. |
---|
| 289 | sceneHandler.EndPrimitives(); |
---|
| 290 | \end{verbatim} |
---|
| 291 | |
---|
| 292 | Most other models are like this, except for the following... |
---|
| 293 | |
---|
| 294 | \item{\tt G4PhysicalVolumeModel} The geometry is descended |
---|
| 295 | recursively, culling policy is enacted, and for each accepted (and |
---|
| 296 | possibly, clipped) solid: |
---|
| 297 | \begin{verbatim} |
---|
| 298 | sceneHandler.PreAddSolid(theAT, *pVisAttribs); |
---|
| 299 | pSol->DescribeYourselfTo(sceneHandler); |
---|
| 300 | // For example, if pSol points to a G4Box... |
---|
| 301 | |-->G4Box::DescribeYourselfTo(G4VGraphicsScene& scene){ |
---|
| 302 | scene.AddSolid(*this); |
---|
| 303 | } |
---|
| 304 | sceneHandler.PostAddSolid(); |
---|
| 305 | \end{verbatim} |
---|
| 306 | |
---|
| 307 | The scene handler may implement the virtual function {\tt |
---|
| 308 | AddSolid(const G4Box\&)}, or inherit: |
---|
| 309 | \begin{verbatim} |
---|
| 310 | void G4VSceneHandler::AddSolid(const G4Box& box) { |
---|
| 311 | RequestPrimitives(box); |
---|
| 312 | } |
---|
| 313 | \end{verbatim} |
---|
| 314 | |
---|
| 315 | {\tt RequestPrimitives} converts the solid into primitives ({\tt G4Polyhedron}) |
---|
| 316 | and invokes {\tt AddPrimitive}: |
---|
| 317 | \begin{verbatim} |
---|
| 318 | BeginPrimitives(*fpObjectTransformation); |
---|
| 319 | pPolyhedron = solid.GetPolyhedron(); |
---|
| 320 | AddPrimitive(*pPolyhedron); |
---|
| 321 | EndPrimitives(); |
---|
| 322 | \end{verbatim} |
---|
| 323 | |
---|
| 324 | The resulting default sequence for a {\tt G4PhysicalVolumeModel} is shown in |
---|
| 325 | Figure \ref{FigPVModel}. |
---|
| 326 | \begin{figure}[t] |
---|
| 327 | \begin{boxedverbatim} |
---|
| 328 | DrawView(); |
---|
| 329 | |-->ProcessView(); |
---|
| 330 | |-->ProcessScene(); |
---|
| 331 | |-->BeginModeling(); |
---|
| 332 | |-->pModel -> DescribeYourselfTo(*this); |
---|
| 333 | | |-->sceneHandler.PreAddSolid(theAT, *pVisAttribs); |
---|
| 334 | | |-->pSol->DescribeYourselfTo(sceneHandler); |
---|
| 335 | | | |-->sceneHandler.AddSolid(*this); |
---|
| 336 | | | |-->RequestPrimitives(solid); |
---|
| 337 | | | |-->BeginPrimitives (*fpObjectTransformation); |
---|
| 338 | | | |-->pPolyhedron = solid.GetPolyhedron(); |
---|
| 339 | | | |-->AddPrimitive(*pPolyhedron); |
---|
| 340 | | | |-->EndPrimitives(); |
---|
| 341 | | |-->sceneHandler.PostAddSolid(); |
---|
| 342 | |-->EndModeling(); |
---|
| 343 | \end{boxedverbatim} |
---|
| 344 | \caption{The default sequence for a {\tt G4PhysicalVolumeModel}} |
---|
| 345 | \label{FigPVModel} |
---|
| 346 | \end{figure} |
---|
| 347 | |
---|
| 348 | Note the sequence of calls at the core: |
---|
| 349 | \begin{verbatim} |
---|
| 350 | sceneHandler.PreAddSolid(theAT, *pVisAttribs); |
---|
| 351 | pSol->DescribeYourselfTo(sceneHandler); |
---|
| 352 | |-->sceneHandler.AddSolid(*this); |
---|
| 353 | |-->RequestPrimitives(solid); |
---|
| 354 | |-->BeginPrimitives (*fpObjectTransformation); |
---|
| 355 | |-->pPolyhedron = solid.GetPolyhedron(); |
---|
| 356 | |-->AddPrimitive(*pPolyhedron); |
---|
| 357 | |-->EndPrimitives(); |
---|
| 358 | sceneHandler.PostAddSolid(); |
---|
| 359 | \end{verbatim} |
---|
| 360 | is reduced to |
---|
| 361 | \begin{verbatim} |
---|
| 362 | sceneHandler.PreAddSolid(theAT, *pVisAttribs); |
---|
| 363 | pSol->DescribeYourselfTo(sceneHandler); |
---|
| 364 | |-->sceneHandler.AddSolid(*this); |
---|
| 365 | sceneHandler.PostAddSolid(); |
---|
| 366 | \end{verbatim} |
---|
| 367 | if the scene handler implements its own {\tt AddSolid}. Moreover, the sequence |
---|
| 368 | \begin{verbatim} |
---|
| 369 | BeginPrimitives (*fpObjectTransformation); |
---|
| 370 | AddPrimitive(*pPolyhedron); |
---|
| 371 | EndPrimitives(); |
---|
| 372 | \end{verbatim} |
---|
| 373 | can be invoked without a prior {\tt PreAddSolid}, etc. The flag {\tt |
---|
| 374 | fProcessingSolid} will be false for the last case. The possibility of |
---|
| 375 | any or all of these three scenarios occurring, for both permanent and |
---|
| 376 | transient objects, affects the implementation of a scene handler if |
---|
| 377 | there is any attempt to build a graphical database. This is reflected |
---|
| 378 | in the templates {\tt XXXStored} and {\tt XXXSG} described in Section |
---|
| 379 | \ref{XXXsub}. Transients are discussed in Section \ref{Transients}. |
---|
| 380 | |
---|
| 381 | \item{\tt G4TrajectoriesModel} At end of event, the trajectory |
---|
| 382 | container is unpacked and, for each trajectory, |
---|
| 383 | {\tt sceneHandler.AddCompound} called. The scene handler may implement this |
---|
| 384 | virtual function or inherit: |
---|
| 385 | \begin{verbatim} |
---|
| 386 | void G4VSceneHandler::AddCompound (const G4VTrajectory& traj) { |
---|
| 387 | traj.DrawTrajectory(((G4TrajectoriesModel*)fpModel)->GetDrawingMode()); |
---|
| 388 | } |
---|
| 389 | \end{verbatim} |
---|
| 390 | Similarly, the user may implement {\tt DrawTrajectory} or inherit: |
---|
| 391 | \begin{verbatim} |
---|
| 392 | void G4VTrajectory::DrawTrajectory(G4int i_mode) const { |
---|
| 393 | G4VVisManager* pVVisManager = G4VVisManager::GetConcreteInstance(); |
---|
| 394 | if (0 != pVVisManager) { |
---|
| 395 | pVVisManager->DispatchToModel(*this, i_mode); |
---|
| 396 | } |
---|
| 397 | } |
---|
| 398 | \end{verbatim} |
---|
| 399 | Thence, the {\tt Draw} method of the current trajectory model is invoked |
---|
| 400 | (see Section \ref{EnhancedTraj} for details on trajectory models), |
---|
| 401 | which in turn, invokes {\tt Draw} methods of the visualisation manager. |
---|
| 402 | The resulting default sequence for a {\tt G4TrajectoriesModel} is shown in |
---|
| 403 | Figure \ref{FigTrajsModel}. |
---|
| 404 | \begin{figure}[t] |
---|
| 405 | \begin{boxedverbatim} |
---|
| 406 | DrawView(); |
---|
| 407 | |-->ProcessView(); |
---|
| 408 | |-->ProcessScene(); |
---|
| 409 | |-->BeginModeling(); |
---|
| 410 | |-->pModel -> DescribeYourselfTo(*this); |
---|
| 411 | | |-->AddCompound(trajectory); |
---|
| 412 | | |-->trajectory.DrawTrajectory(...); |
---|
| 413 | | |-->DispatchToModel(...); |
---|
| 414 | | |-->model->Draw(...); |
---|
| 415 | | |-->G4VisManager::Draw(...); |
---|
| 416 | | |-->BeginPrimitives(objectTransform); |
---|
| 417 | | |-->AddPrimitive(...); |
---|
| 418 | | |-->EndPrimitives(); |
---|
| 419 | |-->EndModeling(); |
---|
| 420 | \end{boxedverbatim} |
---|
| 421 | \caption{The default sequence for a G4TrajectoriesModel} |
---|
| 422 | \label{FigTrajsModel} |
---|
| 423 | \end{figure} |
---|
| 424 | |
---|
| 425 | \end{itemize} |
---|
| 426 | |
---|
| 427 | |
---|
| 428 | \subsection{Dealing with transient objects} |
---|
| 429 | \label{Transients} |
---|
| 430 | |
---|
| 431 | Any visualisable object not defined in the run-duration part of a |
---|
| 432 | scene is treated as ``transient''. This includes trajectories, hits |
---|
| 433 | or anything drawn by the user through the {\tt G4VVisManager} |
---|
| 434 | user-level interface (unless as part of a run-duration model |
---|
| 435 | implementation). A flag, {\tt fReadyForTransients}, is maintained by |
---|
| 436 | the scene handler. In fact, its normal state is {\tt true}, and only |
---|
| 437 | temporarily, during handling of the run-duration part of the scene, is |
---|
| 438 | it set to {\tt false} -- see description of ProcessScene, Section |
---|
| 439 | \ref{ProcessScene}. |
---|
| 440 | |
---|
| 441 | If the driver supports a graphical database, it is smart to |
---|
| 442 | distinguish transient and permanent objects. In this case, every {\tt |
---|
| 443 | Add} method of the scene handler must be transient-aware. In some |
---|
| 444 | cases, it is enough to open a graphical data base component in {\tt |
---|
| 445 | BeginPrimitives}, fill it in {\tt AddPrimitive} and close it |
---|
| 446 | appropriately in {\tt EndPrimitives}. In others, initialisation is |
---|
| 447 | done in {\tt BeginModeling} and consolidation in {\tt EndModeling} -- |
---|
| 448 | see {\tt G4OpenGLStoredSceneHandler}. If any {\tt AddSolid} method is |
---|
| 449 | implemented, then the graphical data base component should be opened |
---|
| 450 | in {\tt PreAddSolid}, protecting against double opening, for example, |
---|
| 451 | \begin{verbatim} |
---|
| 452 | void G4XXXStoredSceneHandler::BeginPrimitives |
---|
| 453 | (const G4Transform3D& objectTransformation) { |
---|
| 454 | G4VSceneHandler::BeginPrimitives(objectTransformation); |
---|
| 455 | // If thread of control has already passed through PreAddSolid, |
---|
| 456 | // avoid opening a graphical data base component again. |
---|
| 457 | if (!fProcessingSolid) { |
---|
| 458 | \end{verbatim} |
---|
| 459 | for other solids. |
---|
| 460 | |
---|
| 461 | The reason for this distinction is that at end of run the user |
---|
| 462 | typically wants to display trajectories on a view of the detector, |
---|
| 463 | then, at the end of the next event\footnote{There is an option to |
---|
| 464 | accumulate trajectories across events and runs -- see commands {\tt |
---|
| 465 | /vis/scene/endOfEventAction} and {\tt /vis/scene/endOfRunAction}.}, |
---|
| 466 | erase the old and see new trajectories. The \vm messages the scene |
---|
| 467 | handler with {\tt ClearTransientStore} just before drawing the |
---|
| 468 | trajectories to achieve this. |
---|
| 469 | |
---|
| 470 | If the driver does not have a graphical database or does not |
---|
| 471 | distinguish between transient and persistent objects, it must emulate |
---|
| 472 | {\tt ClearTransientStore}. Typically, it must erase everything, including |
---|
| 473 | the detector, and re-draw the detector and other run-duration objects, |
---|
| 474 | ready for the transients to be added. File-writing drivers must |
---|
| 475 | rewind the output file. Typically: |
---|
| 476 | \begin{verbatim} |
---|
| 477 | void G4HepRepFileSceneHandler::ClearTransientStore() { |
---|
| 478 | G4VSceneHandler::ClearTransientStore(); |
---|
| 479 | // This is typically called after an update and before drawing hits |
---|
| 480 | // of the next event. To simulate the clearing of "transients" |
---|
| 481 | // (hits, etc.) the detector is redrawn... |
---|
| 482 | if (fpViewer) { |
---|
| 483 | fpViewer -> SetView(); |
---|
| 484 | fpViewer -> ClearView(); |
---|
| 485 | fpViewer -> DrawView(); |
---|
| 486 | } |
---|
| 487 | } |
---|
| 488 | \end{verbatim} |
---|
| 489 | {\tt ClearView} rewinds the output file and {\tt DrawView} re-draws the |
---|
| 490 | detector, etc. (For smart drivers, {\tt DrawView} is smart enough to |
---|
| 491 | know not to redraw the detector, etc., unless the view parameters have |
---|
| 492 | changed significantly -- see Section \ref{DrawView}.) |
---|
| 493 | |
---|
| 494 | |
---|
| 495 | \subsection{More about scene models} |
---|
| 496 | |
---|
| 497 | Scene models conform to the {\tt G4VModel} abstract interface. |
---|
| 498 | Available models are listed and described there in varying detail. |
---|
| 499 | Section \ref{ProcessScene} describes their use in some common command |
---|
| 500 | actions. |
---|
| 501 | |
---|
| 502 | In the design of a new model, care should be taken to handle the |
---|
| 503 | possibility that the {\tt G4ModelingParameters} pointer is zero. |
---|
| 504 | Currently the only use of the modeling parameters is to communicate |
---|
| 505 | the culling policy. Most models, therefore, have no need for modeling |
---|
| 506 | parameters. |
---|
| 507 | |
---|
| 508 | |
---|
| 509 | \section{Enhanced Trajectory Drawing} |
---|
| 510 | \label{EnhancedTraj} |
---|
| 511 | \subsection{Creating a new trajectory model} |
---|
| 512 | New trajectory models must inherit from G4VTrajectoryModel and |
---|
| 513 | implement these pure virtual functions: |
---|
| 514 | |
---|
| 515 | \begin{verbatim} |
---|
| 516 | virtual void Draw(const G4VTrajectory&, G4int i_mode = 0, |
---|
| 517 | const G4bool& visible = true) const = 0; |
---|
| 518 | virtual void Print(std::ostream& ostr) const = 0; |
---|
| 519 | \end{verbatim} |
---|
| 520 | |
---|
| 521 | To use the new model directly in compiled code, simply |
---|
| 522 | register it with the G4VisManager, eg: |
---|
| 523 | |
---|
| 524 | \begin{verbatim} |
---|
| 525 | G4VisManager* visManager = new G4VisExecutive; |
---|
| 526 | visManager->Initialise(); |
---|
| 527 | |
---|
| 528 | // Create custom model |
---|
| 529 | MyCustomTrajectoryModel* myModel = |
---|
| 530 | new MyCustomTrajectoryModel("custom"); |
---|
| 531 | |
---|
| 532 | // Configure it if necessary then register with G4VisManager |
---|
| 533 | ... |
---|
| 534 | visManager->RegisterModel(myModel); |
---|
| 535 | \end{verbatim} |
---|
| 536 | |
---|
| 537 | \subsection{Adding interactive functionality} |
---|
| 538 | |
---|
| 539 | Additional classes need to be written if the new model is to |
---|
| 540 | be created and configured interactively: |
---|
| 541 | |
---|
| 542 | \begin{itemize} |
---|
| 543 | \item {\bf Messenger classes} |
---|
| 544 | |
---|
| 545 | Messengers to configure the model should inherit from |
---|
| 546 | G4VModelCommand. The concrete trajectory model type should be |
---|
| 547 | used for the template parameter, eg: |
---|
| 548 | |
---|
| 549 | \begin{verbatim} |
---|
| 550 | class G4MyCustomModelCommand |
---|
| 551 | : public G4VModelCommand<G4TrajectoryDrawByParticleID> { |
---|
| 552 | ... |
---|
| 553 | }; |
---|
| 554 | |
---|
| 555 | \end{verbatim} |
---|
| 556 | |
---|
| 557 | A number of general use templated commands are available in |
---|
| 558 | G4ModelCommandsT.hh. |
---|
| 559 | |
---|
| 560 | \item {\bf Factory class} |
---|
| 561 | |
---|
| 562 | A factory class responsible for the model and associated messenger |
---|
| 563 | creation must also be written. The factory should inherit from |
---|
| 564 | G4VModelFactory. The abstract model type should be used for the |
---|
| 565 | template parameter, eg: |
---|
| 566 | \begin{verbatim} |
---|
| 567 | class G4TrajectoryDrawByChargeFactory |
---|
| 568 | : public G4VModelFactory<G4VTrajectoryModel> { |
---|
| 569 | ... |
---|
| 570 | }; |
---|
| 571 | \end{verbatim} |
---|
| 572 | |
---|
| 573 | The model and associated messengers should be constructed in the Create |
---|
| 574 | method. Optionally, a context object can also be created, with its own |
---|
| 575 | associated messengers. For example: |
---|
| 576 | |
---|
| 577 | \begin{verbatim} |
---|
| 578 | ModelAndMessengers |
---|
| 579 | G4TrajectoryDrawByParticleIDFactory:: |
---|
| 580 | Create(const G4String& placement, const G4String& name) |
---|
| 581 | { |
---|
| 582 | // Create default context and model |
---|
| 583 | G4VisTrajContext* context = new G4VisTrajContext("default"); |
---|
| 584 | G4TrajectoryDrawByParticleID* model = |
---|
| 585 | new G4TrajectoryDrawByParticleID(name, context); |
---|
| 586 | |
---|
| 587 | // Create messengers for default context configuration |
---|
| 588 | AddContextMsgrs(context, messengers, placement+"/"+name); |
---|
| 589 | |
---|
| 590 | // Create messengers for drawer |
---|
| 591 | messengers.push_back(new |
---|
| 592 | G4ModelCmdSetStringColour<G4TrajectoryDrawByParticleID> |
---|
| 593 | (model, placement)); |
---|
| 594 | messengers.push_back(new |
---|
| 595 | G4ModelCmdSetDefaultColour<G4TrajectoryDrawByParticleID> |
---|
| 596 | (model, placement)); |
---|
| 597 | messengers.push_back(new |
---|
| 598 | G4ModelCmdVerbose<G4TrajectoryDrawByParticleID> |
---|
| 599 | (model, placement)); |
---|
| 600 | |
---|
| 601 | return ModelAndMessengers(model, messengers); |
---|
| 602 | } |
---|
| 603 | \end{verbatim} |
---|
| 604 | |
---|
| 605 | \end{itemize} |
---|
| 606 | |
---|
| 607 | The new factory must then be registered with the visualisation manager. |
---|
| 608 | This should be done by overriding the G4VisManager::RegisterModelFactory |
---|
| 609 | method in a subclass. See, for example, the G4VisManager implementation: |
---|
| 610 | \begin{verbatim} |
---|
| 611 | G4VisExecutive::RegisterModelFactories() |
---|
| 612 | { |
---|
| 613 | ... |
---|
| 614 | RegisterModelFactory(new G4TrajectoryDrawByParticleIDFactory()); |
---|
| 615 | } |
---|
| 616 | \end{verbatim} |
---|
| 617 | |
---|
| 618 | |
---|
| 619 | \section{Trajectory Filtering} |
---|
| 620 | \label{TrajFilter} |
---|
| 621 | \subsection{Creating a new trajectory filter model} |
---|
| 622 | New trajectory filters must inherit at least from G4VFilter. The |
---|
| 623 | models supplied with the Geant4 distribution inherit from |
---|
| 624 | G4SmartFilter, which implements some specialisations on top of |
---|
| 625 | G4VFilter. The models implement these pure virtual functions: |
---|
| 626 | |
---|
| 627 | \begin{verbatim} |
---|
| 628 | // Evaluate method implemented in subclass |
---|
| 629 | virtual G4bool Evaluate(const T&) = 0; |
---|
| 630 | |
---|
| 631 | // Print subclass configuration |
---|
| 632 | virtual void Print(std::ostream& ostr) const = 0; |
---|
| 633 | \end{verbatim} |
---|
| 634 | |
---|
| 635 | To use the new filter model directly in compiled code, simply |
---|
| 636 | register it with the G4VisManager, eg: |
---|
| 637 | |
---|
| 638 | \begin{verbatim} |
---|
| 639 | G4VisManager* visManager = new G4VisExecutive; |
---|
| 640 | visManager->Initialise(); |
---|
| 641 | |
---|
| 642 | // Create custom model |
---|
| 643 | MyCustomTrajectoryFilterModel* myModel = |
---|
| 644 | new MyCustomTrajectoryFilterModel("custom"); |
---|
| 645 | |
---|
| 646 | // Configure it if necessary then register with G4VisManager |
---|
| 647 | ... |
---|
| 648 | visManager->RegisterModel(myModel); |
---|
| 649 | \end{verbatim} |
---|
| 650 | |
---|
| 651 | \subsection{Adding interactive functionality} |
---|
| 652 | |
---|
| 653 | Additional classes need to be written if the new model is to |
---|
| 654 | be created and configured interactively. The mechanism is exactly |
---|
| 655 | the same as that used to create enchanced trajectory drawing |
---|
| 656 | models and associated messengers. See the filter factories in |
---|
| 657 | G4TrajectoryFilterFactories for example implementations. |
---|
| 658 | |
---|
| 659 | \section{Other Resources} |
---|
| 660 | The following sections contain various information for extending |
---|
| 661 | other class functionalities of {\sc Geant4} visualisation: |
---|
| 662 | \begin{itemize} |
---|
| 663 | \item User's Guide for Application Developers, Chapter 8 - Visualization |
---|
| 664 | \item User's Guide for Toolkit Developers, Object-oriented Analysis |
---|
| 665 | and Design of {\sc Geant4} Classes, Chapter \ref{OOChapVis} - |
---|
| 666 | Visualisation |
---|
| 667 | \end{itemize} |
---|
| 668 | |
---|
| 669 | \section{Status of this chapter} |
---|
| 670 | |
---|
| 671 | 03.12.05 ``Enhanced Trajectory Drawing'' added by Jane Tinsley.\\ |
---|
| 672 | 03.12.05 ``Creating a new visualisation driver'' (from Part II) by John Allison.\\ |
---|
| 673 | 09.01.06 ``Creating a new visualisation driver'' considerably expanded by John Allison.\\ |
---|
| 674 | 20.06.06 Some sections improved or added from draft vis paper. John Allison. |
---|