0024610: Visualization, Visual3d_View::MinMaxValues() - skip erased objects while...
[occt.git] / src / Graphic3d / Graphic3d_StructureManager.cdl
1 -- Created on: 1991-09-05
2 -- Created by: NW,JPB,CAL
3 -- Copyright (c) 1991-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 --              11/97 ; CAL : gestion du GraphicClear
18 --              05/98 ; CAL : gestion du GraphicConnect et Disconnect
19
20 deferred class StructureManager from Graphic3d inherits TShared
21
22         ---Version:
23
24         ---Purpose: This class allows the definition of a manager to
25         --          which the graphic objects are associated.
26         --          It allows them to be globally manipulated.
27         --          It defines the global attributes.
28         --  Keywords: Structure, Structure Manager, Update Mode,
29         --     Destroy, Highlight, Visible, Detectable
30
31         ---Warning:
32         ---References:
33
34 uses
35
36         Array2OfReal            from TColStd,
37         SequenceOfInteger       from TColStd,
38
39         GenId                   from Aspect,
40         TypeOfHighlightMethod   from Aspect,
41         TypeOfUpdate            from Aspect,
42
43         ZLayerSettings      from Graphic3d,
44
45         DataStructureManager    from Graphic3d,
46         AspectFillArea3d        from Graphic3d,
47         AspectLine3d            from Graphic3d,
48         AspectMarker3d          from Graphic3d,
49         AspectText3d            from Graphic3d,
50         Structure               from Graphic3d,
51         MapOfStructure          from Graphic3d,
52         SequenceOfStructure     from Graphic3d,
53     GraphicDriver    from Graphic3d
54
55 raises
56
57         InitialisationError     from Graphic3d
58
59 is
60
61         Initialize ( theDriver: GraphicDriver from Graphic3d )
62         ---Level: Public
63         ---Purpose: Initialises the ViewManager.
64         --  Currently creating of more than 100 viewer instances 
65         --  is not supported and leads to InitializationError and 
66         --  initialisation failure.
67         --  This limitation might be addressed in some future OCCT releases.   
68         --  Warning: Raises InitialisationError if the initialisation
69         --          of the ViewManager failed.
70         raises InitialisationError from Graphic3d;
71         -- if the initialisation of the ViewManager failed.
72
73         Destroy ( me     : mutable )
74                 is virtual;
75         ---Level: Public
76         ---Purpose: Deletes the manager <me>.
77         ---C++: alias ~
78
79         ---------------------------------------------------
80         -- Category: Methods to modify the class definition
81         ---------------------------------------------------
82
83         SetPrimitivesAspect ( me        : mutable;
84                               CTX       : AspectLine3d from Graphic3d )
85                 is static;
86         ---Level: Public
87         ---Purpose: Modifies the default attributes for lines
88         --          in the visualiser.
89         ---Category: Methods to modify the class definition
90
91         SetPrimitivesAspect ( me        : mutable;
92                               CTX       : AspectFillArea3d from Graphic3d)
93                 is static;
94         ---Level: Public
95         ---Purpose: Modifies the default attributes for faces
96         --          in the visualiser.
97         ---Category: Methods to modify the class definition
98
99         SetPrimitivesAspect ( me        : mutable;
100                               CTX       : AspectText3d from Graphic3d )
101                 is static;
102         ---Level: Public
103         ---Purpose: Modifies the default attributes for text
104         --          in the visualiser.
105         ---Category: Methods to modify the class definition
106
107         SetPrimitivesAspect ( me        : mutable;
108                               CTX       : AspectMarker3d from Graphic3d)
109                 is static;
110         ---Level: Public
111         ---Purpose: Modifies the default attributes for markers
112         --          in the visualiser.
113         ---Category: Methods to modify the class definition
114
115         ---------------------------------------------------
116         -- Summary of Dynamic Operations and Update Mode --
117         --                                               --
118         -- Use SetUpdateMode  to control when changes to --
119         -- the display are made.                         --
120         --                                               --
121         -- Use one of the  following functions to update --
122         -- one or more views :                           --
123         --                                               --
124         --      Update all views of the viewer :         --
125         --      Visual3d_ViewManager::Update ()          --
126         --                                               --
127         --      Update one view of the viewer            --
128         --      Visual3d_View::Update ()                 --
129         --                                               --
130         -- Use one of the  following functions to update --
131         -- the entire display :                          --
132         --                                               --
133         --      Redraw all structures in all views :     --
134         --      Visual3d_ViewManager::Redraw ()          --
135         --                                               --
136         --      Redraw all structures in one view :      --
137         --      Visual3d_View::Redraw ()                 --
138         ---------------------------------------------------
139
140         SetUpdateMode ( me      : mutable;
141                         AType   : TypeOfUpdate from Aspect )
142                 is static;
143         ---Level: Public
144         ---Purpose: Modifies the screen update mode.
145         --
146         --          TOU_ASAP    as soon as possible
147         --          TOU_WAIT    on demand (with the Update function)
148         --  Note : Dynamic Operations and Update Mode
149         -- Use SetUpdateMode to control when changes to
150         -- the display are made.   Use one of the   following
151         -- functions to update one or more views:
152         -- -   Update all views of the viewer:   Visual3d_ViewManager::Update ()
153         -- -   Update one view of the viewer:   Visual3d_View::Update () Use one of
154         --   the   following functions to update the entire display:
155         -- -   Redraw all structures in all views:   Visual3d_ViewManager::Redraw ()
156         -- -   Redraw all structures in one view:   Visual3d_View::Redraw ()  Update)
157
158         Update ( me )
159                 is deferred;
160         ---Purpose: Updates screen in function of modifications of
161         --          the structures.
162         -- Warning: Not necessary if the update mode is TOU_ASAP.
163
164         ---------------------------------------------
165         -- Category: Inquire methods, MapOfStructure
166         ---------------------------------------------
167
168         DisplayedStructures ( me; SG: in out MapOfStructure  from Graphic3d)
169                 is static;
170         ---Level: Internal
171         ---Purpose: Returns the set of structures displayed in
172         --          visualiser <me>.
173         ---Category: Inquire methods, MapOfStructure
174
175         NumberOfDisplayedStructures ( me )
176                 returns Integer from Standard
177                 is static protected;
178         ---Level: Internal
179         ---Purpose: Returns the number of structures displayed in
180         --          visualiser <me>.
181
182         --DisplayedStructure ( me;
183                 --           AnIndex    : Integer from Standard )
184                 --returns Structure from Graphic3d
185                 --is static protected;
186         ---Level: Internal
187         ---Purpose: Returns the structure displayed in visualiser <me>.
188
189         HighlightedStructures ( me; SG: in out MapOfStructure from Graphic3d )
190                 is static;
191         ---Level: Internal
192         ---Purpose: Returns the set of highlighted structures
193         --          in a visualiser <me>.
194         ---Category: Inquire methods, MapOfStructure
195
196         PickStructures ( me; SG: in out MapOfStructure from Graphic3d )
197                 is static;
198         ---Level: Internal
199         ---Purpose: Returns the set of detectable structures
200         --          in a visualiser <me>.
201         ---Category: Inquire methods, MapOfStructure
202
203         ----------------------------
204         -- Category: Inquire methods
205         ----------------------------
206
207         FillArea3dAspect ( me )
208                 returns AspectFillArea3d from Graphic3d
209                 is static;
210         ---Level: Public
211         ---Purpose: Returns the values of the current default attributes.
212         ---Category: Inquire methods
213
214         Limit ( myclass )
215                 returns Integer from Standard;
216         ---Level: Internal
217         ---Purpose: Returns maximum number of managers defineable.
218         ---Category: Inquire methods
219
220         Line3dAspect ( me )
221                 returns AspectLine3d from Graphic3d
222                 is static;
223         ---Level: Public
224         ---Purpose: Returns the values of the current default attributes.
225         ---Category: Inquire methods
226
227         Marker3dAspect ( me )
228                 returns AspectMarker3d from Graphic3d
229                 is static;
230         ---Level: Public
231         ---Purpose: Returns the values of the current default attributes.
232         ---Category: Inquire methods
233
234         PrimitivesAspect ( me;
235                            CTXL : out AspectLine3d from Graphic3d;
236                            CTXT : out AspectText3d from Graphic3d;
237                            CTXM : out AspectMarker3d from Graphic3d;
238                            CTXF : out AspectFillArea3d from Graphic3d )
239                 is static;
240         ---Level: Public
241         ---Purpose: Returns the values of the current default attributes.
242         ---Category: Inquire methods
243
244         Text3dAspect ( me )
245                 returns AspectText3d from Graphic3d
246                 is static;
247         ---Level: Public
248         ---Purpose: Returns the values of the current default attributes.
249         ---Category: Inquire methods
250
251         UpdateMode ( me )
252                 returns TypeOfUpdate from Aspect
253                 is static;
254         ---Level: Public
255         ---Purpose: Returns the screen update mode.
256         --
257         --          TOU_ASAP    as soon as possible
258         --          TOU_WAIT    on demand (Update)
259         --
260         ---Category: Inquire methods
261
262         ----------------------------
263         -- Category: Private methods
264         ----------------------------
265
266         ChangeDisplayPriority ( me              : mutable;
267                                 AStructure      : Structure from Graphic3d;
268                                 OldPriority     : Integer from Standard;
269                                 NewPriority     : Integer from Standard )
270                 is deferred;
271         ---Level: Internal
272         ---Purpose: Changes the display priority of the structure <AStructure>.
273         ---Category: Private methods
274
275         ChangeZLayer ( me           : mutable;
276                        theStructure : Structure from Graphic3d;
277                        theLayerId   : Integer from Standard )
278            is deferred;
279         ---Purpose: Change Z layer for structure. The z layer mechanism allows
280         -- to display structures in higher layers in overlay of structures in
281         -- lower layers.
282
283         GetZLayer ( me;
284                     theStructure : Structure from Graphic3d )
285            returns Integer from Standard is deferred;
286         ---Purpose: Get Z layer ID assigned to structure. If the structure
287         -- has no layer ID (deleted from graphic driver), the method returns -1.
288
289         SetZLayerSettings ( me          : mutable;
290                             theLayerId  : Integer from Standard;
291                             theSettings : ZLayerSettings from Graphic3d )
292           is deferred;
293         ---Purpose: Sets the settings for a single Z layer for all managed views.
294
295         ZLayerSettings ( me          : mutable;
296                          theLayerId  : Integer from Standard )
297           returns ZLayerSettings from Graphic3d is deferred;
298         ---Purpose: Returns the settings of a single Z layer.
299         
300         AddZLayer ( me : mutable;
301                     theLayerId : in out Integer from Standard )
302            returns Boolean from Standard is deferred;
303         ---Purpose: Add a new top-level Z layer and get its ID as
304         -- <theLayerId> value. The method returns Standard_False if the layer
305         -- can not be created. The z layer mechanism allows to display
306         -- structures in higher layers in overlay of structures in lower layers.
307
308         RemoveZLayer ( me : mutable;
309                        theLayerId : Integer from Standard )
310            returns Boolean from Standard is deferred;
311         ---Purpose: Remove Z layer with ID <theLayerId>. Method returns
312         -- Standard_False if the layer can not be removed or doesn't exists.
313         -- By default, there is always a default bottom-level layer that can't
314         -- be removed.
315
316         GetAllZLayers ( me;
317                         theLayerSeq : out SequenceOfInteger from TColStd )
318            is deferred;
319         ---Purpose: Return all Z layer ids in sequence ordered by level
320         -- from lowest layer to highest. The first layer ID in sequence is
321         -- the default layer that can't be removed.
322
323         CurrentId ( myclass )
324                 returns Integer from Standard;
325         ---Level: Internal
326         ---Purpose: Returns a current identifier available.
327         ---Category: Private methods
328
329         ReCompute ( me          : mutable;
330                     AStructure  : Structure from Graphic3d )
331                 is deferred;
332         ---Level: Advanced
333         ---Purpose: Forces a new construction of the structure <AStructure>
334         --          if <AStructure> is displayed and TOS_COMPUTED.
335         ---Category: Private methods
336
337         ReCompute ( me          : mutable;
338                     AStructure  : Structure from Graphic3d;
339                     AProjector  : DataStructureManager from Graphic3d )
340                 is deferred;
341         ---Level: Advanced
342         ---Purpose: Forces a new construction of the structure <AStructure>
343         --          if <AStructure> is displayed in <AProjector> and TOS_COMPUTED.
344         ---Category: Private methods
345
346         Detectable ( me         : mutable;
347                      AStructure : Structure from Graphic3d )
348                 is static private;
349         ---Level: Internal
350         ---Purpose: Sets detectable the structure <AStructure>.
351         ---Category: Private methods
352
353         Clear ( me              : mutable;
354                 AStructure      : Structure from Graphic3d;
355                 WithDestruction : Boolean from Standard )
356                 is deferred;
357         ---Level: Internal
358         ---Purpose: Clears the structure <AStructure>.
359         ---Category: Private methods
360
361         Connect ( me            : mutable;
362                   AMother       : Structure from Graphic3d;
363                   ADaughter     : Structure from Graphic3d )
364                 is deferred;
365         ---Level: Internal
366         ---Purpose: Connects the structures <AMother> and <ADaughter>.
367         ---Category: Private methods
368
369         Disconnect ( me         : mutable;
370                      AMother    : Structure from Graphic3d;
371                      ADaughter  : Structure from Graphic3d )
372                 is deferred;
373         ---Level: Internal
374         ---Purpose: Disconnects the structures <AMother> and <ADaughter>.
375         ---Category: Private methods
376
377         Display ( me            : mutable;
378                   AStructure    : Structure from Graphic3d )
379                 is deferred;
380         ---Level: Internal
381         ---Purpose: Display the structure <AStructure>.
382         ---Category: Private methods
383
384         Erase ( me              : mutable;
385                 AStructure      : Structure from Graphic3d )
386                 is deferred;
387         ---Level: Internal
388         ---Purpose: Erases the structure <AStructure>.
389         ---Category: Private methods
390
391         Highlight ( me          : mutable;
392                     AStructure  : Structure from Graphic3d;
393                     AMethod     : TypeOfHighlightMethod from Aspect )
394                 is deferred;
395         ---Level: Internal
396         ---Purpose: Highlights the structure <AStructure>.
397         ---Category: Private methods
398
399         SetTransform ( me               : mutable;
400                        AStructure       : Structure from Graphic3d;
401                        ATrsf            : Array2OfReal from TColStd )
402                 is deferred;
403         ---Level: Internal
404         ---Purpose: Transforms the structure <AStructure>.
405         ---Category: Private methods
406
407         GraphicDriver ( me )
408                 returns GraphicDriver from Graphic3d;
409         ---Level: Internal
410         ---Purpose: Returns the graphic driver of <me>.
411         ---Category: Private methods
412   ---C++: return const &
413
414         Identification ( me )
415                 returns Integer from Standard
416                 is virtual;
417         ---Level: Internal
418         ---Purpose: Returns the identification number of the manager.
419         ---Category: Private methods
420
421         Identification ( me;
422                          AId    : Integer from Standard )
423                 returns Structure from Graphic3d
424                 is virtual;
425         ---Level: Internal
426         ---Purpose: Returns the structure with the identification number <AId>.
427         ---Warning: Returns a null structure if the identification number
428         --          is not a structure identifier.
429         ---Category: Private methods
430
431         NewIdentification ( me  : mutable )
432                 returns Integer from Standard
433                 is static;
434         ---Level: Internal
435         ---Purpose: Returns a new identification number for a new structure in the manager.
436
437         Remove ( me     : mutable;
438                  AnId   : Integer from Standard )
439                 is static private;
440         ---Level: Internal
441         ---Purpose: Frees the identifieur <AnId>.
442         ---Category: Private methods
443
444         Undetectable ( me               : mutable;
445                        AStructure       : Structure from Graphic3d )
446                 is static private;
447         ---Level: Internal
448         ---Purpose: Sets no detectable the structure <AStructure>.
449         ---Category: Private methods
450
451         UnHighlight ( me                : mutable )
452                 is deferred;
453         ---Level: Internal
454         ---Purpose: Suppresses the highlighting on all the structures in <me>.
455         ---Category: Private methods
456
457         UnHighlight ( me                : mutable;
458                       AStructure        : Structure from Graphic3d )
459                 is deferred;
460         ---Level: Internal
461         ---Purpose: Suppress the highlighting on the structure <AStructure>.
462         ---Category: Private methods
463
464   RecomputeStructures (me: mutable);
465   -- Purpose: Recomputes all displayed structures. Used to recompute GL
466   -- resources after the last view has been closed without removing objects.
467
468   RecomputeStructures (me: mutable;
469                        theStructures : MapOfStructure from Graphic3d);
470   ---Purpose: Recomputes all structures from theStructures.
471
472 --
473
474 fields
475
476 --
477 -- Class        :       Graphic3d_StructureManager
478 --
479 -- Purpose      :       Declaration of variables specific to managers
480 --
481 -- Reminder     :       A manager manipulates a group of structures
482
483         -- the identifier of the manager
484         MyId                    :       Integer from Standard is protected;
485
486         -- the update display mode
487         MyUpdateMode            :       TypeOfUpdate from Aspect is protected;
488
489         -- the different contexts for primitives
490         MyAspectLine3d          :       AspectLine3d from Graphic3d
491                                                                 is protected;
492         MyAspectText3d          :       AspectText3d from Graphic3d
493                                                                 is protected;
494         MyAspectMarker3d        :       AspectMarker3d from Graphic3d
495                                                                 is protected;
496         MyAspectFillArea3d      :       AspectFillArea3d from Graphic3d
497                                                                 is protected;
498
499         -- the displayed structures
500         MyDisplayedStructure    :       MapOfStructure from Graphic3d
501                                                                 is protected;
502
503         -- the highlighted structures
504         MyHighlightedStructure  :       MapOfStructure from Graphic3d
505                                                                 is protected;
506
507         -- the pickable structures
508         MyPickStructure         :       MapOfStructure from Graphic3d
509                                                                 is protected;
510
511         -- the structure identifier generator
512         MyStructGenId           :       GenId from Aspect is protected;
513
514
515         MyGraphicDriver         :       GraphicDriver from Graphic3d is protected;
516
517 friends
518
519         class Structure from Graphic3d
520
521 end StructureManager;