This commit was generated by cvs2svn to compensate for changes in r2,
[u/mrichter/AliRoot.git] / GEANT321 / gdraw / gdraw.doc
1 *
2 * $Id$
3 *
4 * $Log$
5 * Revision 1.1.1.1  1995/10/24 10:20:18  cernlib
6 * Geant
7 *
8 *
9 #include "geant321/pilot.h"
10 #if defined(CERNLIB_DOC)
11 *CMZ :  3.21/02 29/03/94  15.41.25  by  S.Giani
12 *-- Author :
13 *
14 ************************************************************************
15 *                                                                      *
16 *             Introduction to the Drawing package                      *
17 *             -----------------------------------                      *
18 *                                                                      *
19 *                                                                      *
20 * THE DRAWING PACKAGE                                                  *
21 *                                                                      *
22 * The drawing package has been designed mainly to:                     *
23 *                                                                      *
24 * - draw the detector                                                  *
25 * - draw the detector geometrical tree                                 *
26 * - draw particle trajectories                                         *
27 * - draw hits.                                                         *
28 *                                                                      *
29 *  DRAWING THE DETECTOR                                                *
30 *                                                                      *
31 *  The detector  can be looked at  from any view point  and with any   *
32 * scale factor (GDRAW, GDRVOL); appropriate attributes can be set in   *
33 * order to see  only selected objects (so  avoiding messy pictures);   *
34 * hidden line removal is available as well as surface shading.         *
35 *  'Cut'  views,  i.e.  intersections  of a  given  plane  with  the   *
36 * detector, can also be displayed (GDRAWC, GDRAWX).  This feature is   *
37 * very useful to  see internal details that the  routine GDRAW would   *
38 * not show.                                                            *
39 *  When hidden line  removal is used, the possibility  exists to cut   *
40 * the volume to be drawn with various shapes, to visualise the inner   *
41 * details.                                                             *
42 *                                                                      *
43 * DRAWING THE GEOMETRICAL TREE                                         *
44 *                                                                      *
45 *  The geometrical tree (GDTREE) is  a representation of the overall   *
46 * structure of the detector, namely the mother-daughter relationship   *
47 * among  the  various  objects   composing  it.   Several  types  of   *
48 * additional information are available on request: multiplicity of a   *
49 * given  volume (i.e.  how  many  times it  is  positioned in  other   *
50 * places, or  number of  subdivisions), detector  nature, visibility   *
51 * flag, etc.  This  drawing tree capability can be  very useful when   *
52 * tuning  the  detector  geometry.    If  used  interactively,  this   *
53 * facility  allow to  invoke via  a click  of the  mouse the  GDSPEC   *
54 * utility (see below) for any node of the tree.                        *
55 *                                                                      *
56 * DRAWING THE GEOMETRICAL SPECIFICATIONS                               *
57 *                                                                      *
58 *  The geometrical  specifications (GDSPEC) give a  detailed picture   *
59 * of one  particular piece of  the detector.  Three drawings  of the   *
60 * volume (a projection  view and two cut views), its  shape type and   *
61 * numerical  parameters  (i.e.  dimensions),  and  a  scale  to  aid   *
62 * geometric  calculations,  are  presented   together  in  a  single   *
63 * graphics frame.  The set of  geometrical specifications of all the   *
64 * descendants of  a given node on  the tree, can easily  be obtained   *
65 * with the routine GDFSPC.                                             *
66 *                                                                      *
67 * DRAWING PARTICLE TRAJECTORIES                                        *
68 *                                                                      *
69 *  The tracks generated  by the tracking package, and  stored in the   *
70 * data structure JXYZ, can be easily drawn with the routine GDXYZ.     *
71 *  The names of the particles and/or  the track numbers can be drawn   *
72 * as well (GDPART).                                                    *
73 *  Four types of representations are  used to display the classes of   *
74 * particles, with different colour and line style:                     *
75 *                                                                      *
76 * - red solid lines for charged particles (GTELEC, GTHADR)             *
77 * - green dashed lines for muons (GTMUON)                              *
78 * - black blank/dotted lines for neutral particles (GTNEUT)            *
79 * - blue dotted lines for gammas (GTGAMA)                              *
80 *                                                                      *
81 *  A special routine has been  provided to display the tracks online   *
82 * (GDCXYZ), if  called under  the DEBUG/SWITCH control  from GUSTEP.   *
83 * That routine  shows the tracks exactly  at the same time  they are   *
84 * trasorted by  the tracking package  of GEANT3, giving so  a useful   *
85 * interactive debugging tool.                                          *
86 *                                                                      *
87 * DRAWING HITS                                                         *
88 *                                                                      *
89 *  The hits generated by the tracking package and stored in the        *
90 * data structure JHITS, can be displayed by the hits routines,         *
91 * with different functionality:                                        *
92 *                                                                      *
93 * - draw one hit (GDAHIT); called by user routines                     *
94 * - draw all the hits of trajectory type sets/detectors (GDHITS)       *
95 * - draw all the hits of calorimeter type sets/detectors (GDCHIT)      *
96 *                                                                      *
97 *  Different symbols for every subdetector can be used, chosen among   *
98 * hardware characters  (dots), software  crosses, or from  the HPLOT   *
99 * table of software characters.  The size of the software characters   *
100 * and crosses is given as an  argument to GDAHIT/GDHITS, while it is   *
101 * computed as a function of the hits value in GDCHIT.                  *
102 *                                                                      *
103 * THE VIEW BANKS                                                       *
104 *                                                                      *
105 *  The basic detector drawing  routines (GDRAW, GDRAWC, GDRAWX) have   *
106 * to scan the  data structure JVOLUM repeatedly.   When the detector   *
107 * is  described in  a  very  detailed way,  the  time  spent in  the   *
108 * interpretation of  the JVOLUM bank  and in the  3D transformations   *
109 * can  increase dramatically.   For a  detector with  more than  100   *
110 * different volume names, for example, this time can reach real time   *
111 * minutes on some machines, whereas  the specific time required just   *
112 * by the  drawing would be only  a few seconds.  If  the hidden line   *
113 * removal option is active, this  time can reach several minutes and   *
114 * even  hours,  depending  on  the  speed of  the  machine  and  the   *
115 * complexity of the drawing requested.                                 *
116 *  In order to alleviate this  problem the 'bank-mode' routines have   *
117 * been developed.  The basic idea  is to separate the interpretation   *
118 * (i.e. the  JVOLUM scanning  to convert  the 3D  geometry structure   *
119 * into a set of 2D lines) from the drawing itself.  In this way, the   *
120 * interpretation is performed  only once and all  the 2D information   *
121 * is stored in view banks  (data structure JDRAW) [DRAW 399].  These   *
122 * views can then be looked at in  a quicker way, having only to draw   *
123 * all 2D vectors  previously stored.  For a detector  with more than   *
124 * 100 different volume  names, for example, this is  achieved at the   *
125 * cost of only a few thousand words of memory for each view bank.      *
126 *  One  can therefore  open a  view bank  (GDOPEN), identified  by a   *
127 * number, perform appropriate drawings  (only interpretation will be   *
128 * made, of course), close the bank  (GDCLOS) and finally look at the   *
129 * picture stored in  it (GDSHOW).  When a view bank  has been closed   *
130 * it cannot  be modified anymore,  but it  can be displayed  as many   *
131 * times as wanted (GDSHOW) or deleted (GDELET).                        *
132 *                                                                      *
133 * OTHER FEATURES                                                       *
134 *                                                                      *
135 *  The user can  control some drawing options  (GDOPT), by selecting   *
136 * for instance  to have  either parallel or  perspective projection,   *
137 * either  Y-Z  or  R-Z  projection,  hidden  line  removal,  surface   *
138 * shading, etc.                                                        *
139 *  There is  a routine (GDZOOM) that,  if called, applies a  zoom to   *
140 * everything (volumes, tracks, hits, etc.)  will be drawn from then.   *
141 * This feature, in conjunction  with the interactive command MEASURE   *
142 * [XINT 110], can be used for detailed viewing.                        *
143 *  Another  tool that  could help  in the  interactive debugging  or   *
144 * tuning of the detector geometry  is the routine GEDITV [DRAW 600],   *
145 * by which it  is possible to modify  interactively some geometrical   *
146 * parameters  set  by  the   user  routines  defining  the  detector   *
147 * geometry.                                                            *
148 *  It is possible to draw the axes of the 3D MAster Reference System   *
149 * (GDAXIS) oriented in agreement with the current view point.          *
150 *  Two other  routines draw a scale  (GDSCAL) or a profile  of a man   *
151 * (GDMAN) in 2D  user coordinates to give an idea  of the dimensions   *
152 * within current scale  factors.  A 2D text  (GDRAWT) using software   *
153 * characters (hardware  characters should be implemented  later on),   *
154 * 2D vectors (GDRAWV) or a frame header (GDHEAD) are also available.   *
155 *  Attributes  like colour  (GDCOL)  and line  width  (GDLW) can  be   *
156 * globally set for all 2D  drawings (i.e. text, vectors, man, etc.);   *
157 * they are overridden in 3D drawings by volume attributes set by the   *
158 * GSATT routine with 'COLO' or 'LWID' option.                          *
159 *  A  graphics input  is available  (GDCURS)  to fetch  the 2D  user   *
160 * coordinates  of the  graphics cursor  on the  screen, allowing  an   *
161 * immediate user  interface with the interactive  version of GEANT3.   *
162 * In  particular there  are interactive  commands to  zoom, measure,   *
163 * pick tracks or hits points that make use of that routine.            *
164 *  Various conversions from  3D to 3D, and 3D to  2D coordinates are   *
165 * performed by GDFR3D and GD3D3D.                                      *
166 *                                                                      *
167 * BASIC AND ADVANCED GRAPHICS                                          *
168 *                                                                      *
169 *  The  underlying graphics  system  is completely  hidden from  the   *
170 * GEANT program.  All  graphics call are made via  the HIGZ package.   *
171 * Various implementations of the HIGZ package are available, notably   *
172 * for X11, GKS, DI3000 and, shortly, PHIGS.                            *
173 *                                                                      *
174 *  RUNNING INSTRUCTIONS                                                *
175 *                                                                      *
176 *  Thanks to the HIGZ package,  it is possible to produce postscript   *
177 * metafiles from the drawings.  When  the GKS implementation of HIGZ   *
178 * is used, the possibility is there  to produce also a GKS metafile.   *
179 *                                                                      *
180 * SUMMARY                                                              *
181 *                                                                      *
182 *  The drawing package is initialized by (in the order):               *
183 *  IGINIT    to initialize the HIGZ package and the underlying basic   *
184 *            graphics software                                         *
185 *  GDINIT    to initialize the GEANT drawing package                   *
186 *                                                                      *
187 *  Main drawing routines are:                                          *
188 *  GDRAW     to draw a projection view of the detector                 *
189 *  GDRVOL    to draw a projection view of the detector                 *
190 *  GDRAWC    to draw a cut view of the detector (along one axis)       *
191 *  GDRAWX    to draw a cut view of the detector (from any point)       *
192 *  GDXYZ     to draw tracks at the end of the event                    *
193 *  GDCXYZ    to draw tracks while the event is running                 *
194 *  GDPART    to draw particle names and track numbers on tracks        *
195 *  GDAHIT    to draw one single hit                                    *
196 *  GDHITS    to draw hits for trajectory type detectors                *
197 *  GDCHIT    to draw hits for calorimeter type detectors               *
198 *                                                                      *
199 *  Routines that show how the detector has been modeled are:           *
200 *  GDTREE    to draw a picture with the geometrical tree               *
201 *  GDSPEC    to draw a picture with volume specifications              *
202 *  GDFSPC    to draw several GDSPEC pictures                           *
203 *                                                                      *
204 *  Routines that perform control operations on view banks are:         *
205 *  GDOPEN    to open a given view bank, identified by a view number;   *
206 *            in this way we enter in bank-mode                         *
207 *  GDCLOS    to close  current view bank, i.e. the last  one opened,   *
208 *            and restore screen-mode                                   *
209 *  GDSHOW    to show all graphics information contained  in a  given   *
210 *            view bank                                                 *
211 *  GDELET    to delete a given view bank from memory                   *
212 *                                                                      *
213 *  Other routines are:                                                 *
214 *  GDOPT     to set drawing options                                    *
215 *  GDZOOM    to set the zoom parameters                                *
216 *  GDAXIS    to draw the axes of  the MARS,  oriented according        *
217 *            to the current view parameters                            *
218 *  GDSCAL    to draw the current scale                                 *
219 *  GDMAN     to draw a profile of a man  (or a woman) at the current   *
220 *            scale                                                     *
221 *  GDRAWT    to draw text, with software characters                    *
222 *  GDRAWV    to draw polylines in 2D user coordinates                  *
223 *  GDHEAD    to draw a frame header                                    *
224 *  GDCOL     to set colour code                                        *
225 *  GDLW      to set line width                                         *
226 *  GDCURS    to have an input from the graphics cursor                 *
227 *  GDFR3D    to convert from 3D coordinates (either in MARS or DRS)    *
228 *            to 2D user coordinates                                    *
229 *  GD3D3D    to convert from 3D MARS coordinates to  3D  Projection    *
230 *            Reference System coordinates.                             *
231 *                                                                      *
232 *        Labelled COMMON blocks related to section DRAW                *
233 *        ----------------------------------------------                *
234 *                                                                      *
235 *    COMMON/GCDRAW/NUMNOD,MAXNOD,NUMND1,LEVVER,LEVHOR,MAXV,IPICK,      *
236 *   + MLEVV,MLEVH,NWCUT,JNAM,JMOT,JXON,JBRO,JDUP,JSCA,JDVM,JPSM,       *
237 *   + JNAM1,JMOT1,JXON1,JBRO1,JDUP1,JSCA1,JULEV,JVLEV,                 *
238 *   + LOOKTB(16),                                                      *
239 *   + GRMAT0(10),GTRAN0(3),IDRNUM,GSIN(41),GCOS(41),SINPSI,COSPSI,     *
240 *   + GTHETA,GPHI,GPSI,GU0,GV0,GSCU,GSCV,NGVIEW,                       *
241 *   + ICUTFL,ICUT,CTHETA,CPHI,DCUT,NSURF,ISURF,                        *
242 *   + GZUA,GZVA,GZUB,GZVB,GZUC,GZVC,PLTRNX,PLTRNY,                     *
243 *   + LINATT,LINATP,ITXATT,ITHRZ,IPRJ,DPERS,ITR3D,IPKHIT,IOBJ,LINBUF,  *
244 *   + MAXGU,MORGU,MAXGS,MORGS,MAXTU,MORTU,MAXTS,MORTS,                 *
245 *   + IGU,IGS,ITU,ITS,NKVIEW,IDVIEW,                                   *
246 *   + NOPEN,IGMR,IPIONS,ITRKOP,IHIDEN,                                 *
247 *   + DDUMMY(18)                                                       *
248 * C                                                                    *
249 * NUMNOD  number of nodes in non-optimized tree                        *
250 * MAXNOD  max. number of nodes of non-optimized tree.                  *
251 * NUMND1  number of nodes in optimized tree                            *
252 * LEVVER  vertical level in the tree currently scanned                 *
253 * LEVHOR  horizontal node in the tree currently scanned                *
254 * MAXV    max vertical levels in the tree to be scanned                *
255 * IPICK   node selected by GDTREE                                      *
256 * MLEVV   number of vertical levels in the last tree scanned           *
257 * MLEVH   number of horizontal nodes in the last tree scanned          *
258 * NWCUT   max. workspace allocated by cut routines                     *
259 * JNAM-JVLEV   pointers used by the tree routines                      *
260 * LOOKTB  colour look-up table, LOOKTB(I)=I,I=1,16                     *
261 * GRMAT0  rotation matrix saved by GDRVOL                              *
262 * GTRAN0  translation matrix saved by GDRVOL                           *
263 * IDRNUM  flag for GDRAW, set to 1 when called by GDRVOL               *
264 * GSIN    sine table                                                   *
265 * GCOS    cosine table                                                 *
266 * SINPSI  SIN(GPSI*DEGRAD)                                             *
267 * COSPSI  COS(GPSI DEGRAD)                                             *
268 * GTHETA  Theta angle of the parallel projection of 3-D images         *
269 * GPHI    Phi angle of the parallel projection of 3-D images           *
270 * GPSI    Psi angle of rotation of the image on the screen             *
271 * GU0     U position (X in screen coordinates) of the origin           *
272 * GV0     V position (Y in screen coordinates) of the origin           *
273 * GSCU    scale factor for the U screen coordinate                     *
274 * GSCV    scale factor for the V screen coordinate                     *
275 * NGVIEW  flag for GDFR3D and GD3D3D if view point has changed         *
276 * ICUTFL  flag for GDRAW if it was called by cut routines              *
277 * ICUT    axis along which the cut is performed                        *
278 * CTHETA  Theta angle of cut supplied to GDRAWX                        *
279 * CPHI    Phi angle of cut supplied to GDRAWX                          *
280 * DCUT    coordinate value at which the cut is performed               *
281 * NSURF   number of surfaces stored in SURF                            *
282 * ISURF   pointer for array SURF                                       *
283 * GZUA    zoom parameter (horizontal scale factor)                     *
284 * GZVA    zoom parameter (vertical scale factor)                       *
285 * GZUB    zoom parameter                                               *
286 * GZVB    zoom parameter                                               *
287 * GZUC    zoom parameter                                               *
288 * GZVC    zoom parameter                                               *
289 * PLTRNX  screen and plotter X range                                   *
290 * PLTRNY  screen and plotter Y range                                   *
291 * LINATT  current line attributes                                      *
292 * LINATP  permanent line attributes                                    *
293 * ITXATT  current text attributes                                      *
294 * ITHRZ   string containing the status of THRZ option                  *
295 * IPRJ    string containing the status of PROJ option                  *
296 * DPERS   distance from the origin for perspective view                *
297 * ITR3D   track being scanned                                          *
298 * IPKHIT  flag for GPHITS, if>0 then print only hit number             *
299 * IOBJ    type of the object being drawn                               *
300 * LINBUF  flag for GDRAWV if line buffering is active                  *
301 * MAXGU   current physical number of words for graphic unit banks      *
302 * MORGU   number of words to be pushed in graphic unit banks           *
303 * MAXGS   current physical number of words for graphic segment banks   *
304 * MORGS   number of words to be pushed in graphic segment banks        *
305 * MAXTU   current physical number of words for text unit banks         *
306 * MORTU   number of words to be pushed in text unit banks              *
307 * MAXTS   current physical number of words for text segment banks      *
308 * MORTS   number of words to be pushed in text segment banks           *
309 * IGU     pointer to current graphic unit bank                         *
310 * IGS     pointer to current graphic segment bank                      *
311 * ITU     pointer to current text unit bank                            *
312 * ITS     pointer to current text segment bank                         *
313 * NKVIEW  number of view data banks                                    *
314 * IGVIEW  current view bank number or 0 for screen                     *
315 * NOPEN   unused                                                       *
316 * IGMR    unused                                                       *
317 * IPIONS  unused                                                       *
318 * ITRKOP  status of TRAK option of GDOPT                               *
319 * DDUMMY  array of dummy words                                         *
320 *                                                                      *
321 *                                                                      *
322 *                                                                      *
323 *                The View data structure JDRAW                         *
324 *                -----------------------------                         *
325 *                                                                      *
326 * NKVIEW    Number of views                                            *
327 * IVIEW     Current view selected                                      *
328 * IGU       Current graphic unit pointer                               *
329 * MAXGU     Number of graphic units                                    *
330 * MORGU     Number of words to push in graphic unit bank               *
331 * IGS       Current graphic segment pointer                            *
332 * MAXGS     Number of graphic segments                                 *
333 * MORGS     Number of words to push in graphic segment bank            *
334 * ITU       Current text unit pointer                                  *
335 * MAXTU     Number of text units                                       *
336 * MORTU     Number of words to push in text unit bank                  *
337 * ITS       Current text segment pointer                               *
338 * MAXTS     Number of text segments                                    *
339 * MORTS     Number of words to push in text segment bank               *
340 * LENGU     Array containing: lengths for each graphic unit + LINATT   *
341 *           (line attributes)                                          *
342 * ADDGU     Array containing addresses for each graphic unit           *
343 * ADDTU     Array containing addresses for each text unit              *
344 * X         Array containing u-coordinates of graphic segments         *
345 * Y         Array containing v-coordinates of graphic segments         *
346 * ICUT      Cut axis (1,2,3 or 0 if no cut) of the view                *
347 * LINWID    Text line width + ITXATT (text attributes)                 *
348 * GTHETA,  GPHI,  GPSI,  GU0,  GV0,  GSCU,  GSCV,  are  the  viewing   *
349 * parameters stored in /GCDRAW/.                                       *
350 * U0, V0,  SIZE, ANGLE, IOPT, ITEXT  have the same meaning  of those   *
351 * given as parameters in HPLSOF or GDRAWT routines.                    *
352 *  A control word is stored  in Q(JDRAW+IVIEW), to identify the view   *
353 * banks among three classes:                                           *
354 *                                                                      *
355 *  =1 for empty  banks (created just  to avoid gaps) or  for deleted   *
356 *     banks;                                                           *
357 *  =2 for all previously created banks (i.e. opened);                  *
358 *  =3 for protected  banks (all banks  that can't be deleted  by the   *
359 *     user with GDELET, because reserved for internal use).            *
360 *                                                                      *
361 *                           | JDRAW                                    *
362 *                           |                                          *
363 *     NKVIEW   IVIEW        v                 NKVIEW                   *
364 *       ........................................                       *
365 *       |     | |          | |  Control words  |                       *
366 *       ........................................                       *
367 *              |                                                       *
368 *              | JV = LQ(JDRAW-IVIEW)                                  *
369 *  6           v                                           22          *
370 * ............................................................         *
371 * | | | | | | | |igu,maxgu,morgu,igs,maxgs,morgs,itu,maxtu,  |         *
372 * | | | | | | | |        mortu,its,maxts,morts,gtheta,gphi,  |         *
373 * | | | | | | | |        gpsi,gu0,gv0,gscu,gscv,-,-,icut     |         *
374 * ............................................................         *
375 *  | | | | | |                                                         *
376 *  | | | | | | JV1 = LQ(JV-1)                                          *
377 *  | | | | | v                                          MAXGU          *
378 *  | | | | |..................................................         *
379 *  | | | | || | lengu(1) | .... | lengu(igu) | .... | lengu(mgu)       *
380 *  | | | | |..................................................         *
381 *  | | | | |                                                           *
382 *  | | | | | JV2 = LQ(JV-2)                                            *
383 *  | | | | v                                            MAXGU          *
384 *  | | | |....................................................         *
385 *  | | | || | addgu(1) | ..... | addgu(igu) | ..... | addgu(mgu)       *
386 *  | | | |....................................................         *
387 *  | | | |                                                             *
388 *  | | | |  JV3 = LQ(JV-3)                                             *
389 *  | | | v                                              MAXTU          *
390 *  | | |......................................................         *
391 *  | | || | addtu(1) | ...... | addtu(itu) | ...... | addtu(mtu)       *
392 *  | | |......................................................         *
393 *  | | |                                                               *
394 *  | | | JV4 = LQ(JV-4)                                                *
395 *  | | v                                                MAXGS          *
396 *  | |........................................................         *
397 *  | || |  x(1)  |  ......  |  x(igs)  |  ......  |  x(mgs)  |         *
398 *  | |........................................................         *
399 *  | |                                                                 *
400 *  | | JV5 = LQ(JV-5)                                                  *
401 *  | v                                                  MAXGS          *
402 *  |..........................................................         *
403 *  || |   y(1)  |  ......  |  y(igs)  |  ......  |  y(mgs)   |         *
404 *  |..........................................................         *
405 *  |                                                                   *
406 *  | JV6 = LQ(JV-6)                                                    *
407 *  v                                                    MAXTS          *
408 * ............................................................         *
409 * | |u0(1)|v0(1)|size(1)|angle(1)|linwid(1)|iopt(1)|itext(1)|nchar(1)|.*
410 *  ............................................................        *
411 *                                                                      *
412 ************************************************************************
413 #endif