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