557fe41453c5a1627f296e3dc123d80cf1123dfb
[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         MinMaxValues ( me;
235                        XMin, YMin, ZMin : out Real from Standard;
236                        XMax, YMax, ZMax : out Real from Standard )
237                 is static;
238         ---Level: Public
239         ---Purpose: Returns the coordinates of the boundary box of all
240         --          structures displayed in the manager <me>.
241         ---Category: Inquire methods
242
243         PrimitivesAspect ( me;
244                            CTXL : out AspectLine3d from Graphic3d;
245                            CTXT : out AspectText3d from Graphic3d;
246                            CTXM : out AspectMarker3d from Graphic3d;
247                            CTXF : out AspectFillArea3d from Graphic3d )
248                 is static;
249         ---Level: Public
250         ---Purpose: Returns the values of the current default attributes.
251         ---Category: Inquire methods
252
253         Text3dAspect ( me )
254                 returns AspectText3d from Graphic3d
255                 is static;
256         ---Level: Public
257         ---Purpose: Returns the values of the current default attributes.
258         ---Category: Inquire methods
259
260         UpdateMode ( me )
261                 returns TypeOfUpdate from Aspect
262                 is static;
263         ---Level: Public
264         ---Purpose: Returns the screen update mode.
265         --
266         --          TOU_ASAP    as soon as possible
267         --          TOU_WAIT    on demand (Update)
268         --
269         ---Category: Inquire methods
270
271         ----------------------------
272         -- Category: Private methods
273         ----------------------------
274
275         ChangeDisplayPriority ( me              : mutable;
276                                 AStructure      : Structure from Graphic3d;
277                                 OldPriority     : Integer from Standard;
278                                 NewPriority     : Integer from Standard )
279                 is deferred;
280         ---Level: Internal
281         ---Purpose: Changes the display priority of the structure <AStructure>.
282         ---Category: Private methods
283
284         ChangeZLayer ( me           : mutable;
285                        theStructure : Structure from Graphic3d;
286                        theLayerId   : Integer from Standard )
287            is deferred;
288         ---Purpose: Change Z layer for structure. The z layer mechanism allows
289         -- to display structures in higher layers in overlay of structures in
290         -- lower layers.
291
292         GetZLayer ( me;
293                     theStructure : Structure from Graphic3d )
294            returns Integer from Standard is deferred;
295         ---Purpose: Get Z layer ID assigned to structure. If the structure
296         -- has no layer ID (deleted from graphic driver), the method returns -1.
297
298         SetZLayerSettings ( me          : mutable;
299                             theLayerId  : Integer from Standard;
300                             theSettings : ZLayerSettings from Graphic3d )
301           is deferred;
302         ---Purpose: Sets the settings for a single Z layer for all managed views.
303
304         ZLayerSettings ( me          : mutable;
305                          theLayerId  : Integer from Standard )
306           returns ZLayerSettings from Graphic3d is deferred;
307         ---Purpose: Returns the settings of a single Z layer.
308         
309         AddZLayer ( me : mutable;
310                     theLayerId : in out Integer from Standard )
311            returns Boolean from Standard is deferred;
312         ---Purpose: Add a new top-level Z layer and get its ID as
313         -- <theLayerId> value. The method returns Standard_False if the layer
314         -- can not be created. The z layer mechanism allows to display
315         -- structures in higher layers in overlay of structures in lower layers.
316
317         RemoveZLayer ( me : mutable;
318                        theLayerId : Integer from Standard )
319            returns Boolean from Standard is deferred;
320         ---Purpose: Remove Z layer with ID <theLayerId>. Method returns
321         -- Standard_False if the layer can not be removed or doesn't exists.
322         -- By default, there is always a default bottom-level layer that can't
323         -- be removed.
324
325         GetAllZLayers ( me;
326                         theLayerSeq : out SequenceOfInteger from TColStd )
327            is deferred;
328         ---Purpose: Return all Z layer ids in sequence ordered by level
329         -- from lowest layer to highest. The first layer ID in sequence is
330         -- the default layer that can't be removed.
331
332         CurrentId ( myclass )
333                 returns Integer from Standard;
334         ---Level: Internal
335         ---Purpose: Returns a current identifier available.
336         ---Category: Private methods
337
338         ReCompute ( me          : mutable;
339                     AStructure  : Structure from Graphic3d )
340                 is deferred;
341         ---Level: Advanced
342         ---Purpose: Forces a new construction of the structure <AStructure>
343         --          if <AStructure> is displayed and TOS_COMPUTED.
344         ---Category: Private methods
345
346         ReCompute ( me          : mutable;
347                     AStructure  : Structure from Graphic3d;
348                     AProjector  : DataStructureManager from Graphic3d )
349                 is deferred;
350         ---Level: Advanced
351         ---Purpose: Forces a new construction of the structure <AStructure>
352         --          if <AStructure> is displayed in <AProjector> and TOS_COMPUTED.
353         ---Category: Private methods
354
355         Detectable ( me         : mutable;
356                      AStructure : Structure from Graphic3d )
357                 is static private;
358         ---Level: Internal
359         ---Purpose: Sets detectable the structure <AStructure>.
360         ---Category: Private methods
361
362         Clear ( me              : mutable;
363                 AStructure      : Structure from Graphic3d;
364                 WithDestruction : Boolean from Standard )
365                 is deferred;
366         ---Level: Internal
367         ---Purpose: Clears the structure <AStructure>.
368         ---Category: Private methods
369
370         Connect ( me            : mutable;
371                   AMother       : Structure from Graphic3d;
372                   ADaughter     : Structure from Graphic3d )
373                 is deferred;
374         ---Level: Internal
375         ---Purpose: Connects the structures <AMother> and <ADaughter>.
376         ---Category: Private methods
377
378         Disconnect ( me         : mutable;
379                      AMother    : Structure from Graphic3d;
380                      ADaughter  : Structure from Graphic3d )
381                 is deferred;
382         ---Level: Internal
383         ---Purpose: Disconnects the structures <AMother> and <ADaughter>.
384         ---Category: Private methods
385
386         Display ( me            : mutable;
387                   AStructure    : Structure from Graphic3d )
388                 is deferred;
389         ---Level: Internal
390         ---Purpose: Display the structure <AStructure>.
391         ---Category: Private methods
392
393         Erase ( me              : mutable;
394                 AStructure      : Structure from Graphic3d )
395                 is deferred;
396         ---Level: Internal
397         ---Purpose: Erases the structure <AStructure>.
398         ---Category: Private methods
399
400         Highlight ( me          : mutable;
401                     AStructure  : Structure from Graphic3d;
402                     AMethod     : TypeOfHighlightMethod from Aspect )
403                 is deferred;
404         ---Level: Internal
405         ---Purpose: Highlights the structure <AStructure>.
406         ---Category: Private methods
407
408         SetTransform ( me               : mutable;
409                        AStructure       : Structure from Graphic3d;
410                        ATrsf            : Array2OfReal from TColStd )
411                 is deferred;
412         ---Level: Internal
413         ---Purpose: Transforms the structure <AStructure>.
414         ---Category: Private methods
415
416         GraphicDriver ( me )
417                 returns GraphicDriver from Graphic3d;
418         ---Level: Internal
419         ---Purpose: Returns the graphic driver of <me>.
420         ---Category: Private methods
421   ---C++: return const &
422
423         Identification ( me )
424                 returns Integer from Standard
425                 is virtual;
426         ---Level: Internal
427         ---Purpose: Returns the identification number of the manager.
428         ---Category: Private methods
429
430         Identification ( me;
431                          AId    : Integer from Standard )
432                 returns Structure from Graphic3d
433                 is virtual;
434         ---Level: Internal
435         ---Purpose: Returns the structure with the identification number <AId>.
436         ---Warning: Returns a null structure if the identification number
437         --          is not a structure identifier.
438         ---Category: Private methods
439
440         NewIdentification ( me  : mutable )
441                 returns Integer from Standard
442                 is static;
443         ---Level: Internal
444         ---Purpose: Returns a new identification number for a new structure in the manager.
445
446         Remove ( me     : mutable;
447                  AnId   : Integer from Standard )
448                 is static private;
449         ---Level: Internal
450         ---Purpose: Frees the identifieur <AnId>.
451         ---Category: Private methods
452
453         Undetectable ( me               : mutable;
454                        AStructure       : Structure from Graphic3d )
455                 is static private;
456         ---Level: Internal
457         ---Purpose: Sets no detectable the structure <AStructure>.
458         ---Category: Private methods
459
460         UnHighlight ( me                : mutable )
461                 is deferred;
462         ---Level: Internal
463         ---Purpose: Suppresses the highlighting on all the structures in <me>.
464         ---Category: Private methods
465
466         UnHighlight ( me                : mutable;
467                       AStructure        : Structure from Graphic3d )
468                 is deferred;
469         ---Level: Internal
470         ---Purpose: Suppress the highlighting on the structure <AStructure>.
471         ---Category: Private methods
472
473   RecomputeStructures (me: mutable);
474   -- Purpose: Recomputes all displayed structures. Used to recompute GL
475   -- resources after the last view has been closed without removing objects.
476
477   RecomputeStructures (me: mutable;
478                        theStructures : MapOfStructure from Graphic3d);
479   ---Purpose: Recomputes all structures from theStructures.
480
481 --
482
483 fields
484
485 --
486 -- Class        :       Graphic3d_StructureManager
487 --
488 -- Purpose      :       Declaration of variables specific to managers
489 --
490 -- Reminder     :       A manager manipulates a group of structures
491
492         -- the identifier of the manager
493         MyId                    :       Integer from Standard is protected;
494
495         -- the update display mode
496         MyUpdateMode            :       TypeOfUpdate from Aspect is protected;
497
498         -- the different contexts for primitives
499         MyAspectLine3d          :       AspectLine3d from Graphic3d
500                                                                 is protected;
501         MyAspectText3d          :       AspectText3d from Graphic3d
502                                                                 is protected;
503         MyAspectMarker3d        :       AspectMarker3d from Graphic3d
504                                                                 is protected;
505         MyAspectFillArea3d      :       AspectFillArea3d from Graphic3d
506                                                                 is protected;
507
508         -- the displayed structures
509         MyDisplayedStructure    :       MapOfStructure from Graphic3d
510                                                                 is protected;
511
512         -- the highlighted structures
513         MyHighlightedStructure  :       MapOfStructure from Graphic3d
514                                                                 is protected;
515
516         -- the pickable structures
517         MyPickStructure         :       MapOfStructure from Graphic3d
518                                                                 is protected;
519
520         -- the structure identifier generator
521         MyStructGenId           :       GenId from Aspect is protected;
522
523
524         MyGraphicDriver         :       GraphicDriver from Graphic3d is protected;
525
526 friends
527
528         class Structure from Graphic3d
529
530 end StructureManager;