0024837: Visualization - revise design and implementation of connected Interactive...
[occt.git] / src / PrsMgr / PrsMgr_PresentableObject.cdl
1 -- Created on: 1995-01-25
2 -- Created by: Jean-Louis Frenkel
3 -- Copyright (c) 1995-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 -- Modified by  Rob (18/12/96) -> information about modes to update.
18 --              Rob (04/07/97) ->   TypeOfPresentation3d () Method 
19 --                                  changed to Public Method.
20 --                             -> Option Projector Dependant/Independant
21 --                                may be set at any time , not only in
22 --                                the constructor or the presentable.
23 --                               ->Insert Locations Methods...
24 --              Rob (16/12/97) -> Get the list of modes to be updated
25 --                             -> Flags all the Prs to be updated...                 
26 --              GG IMP020200   -> Presentations() method become protected
27 --                              and no more private.
28 --              SAN (22/03/04) -> OCC4895 High-level interface for controlling 
29 --                              polygon offsets: Fill() made protected virtual.
30
31 deferred class PresentableObject from PrsMgr inherits TShared from MMgt
32
33
34         ---Purpose: A framework to supply the Graphic3d
35         -- structure of the object to be presented. On the first
36         -- display request, this structure is created by calling the
37         -- appropriate algorithm and retaining this frameworkfor
38         -- further display.
39         -- This abstract framework is inherited in Application
40         -- Interactive Services (AIS), notably in:
41         -- -   AIS_InteractiveObject
42         -- -   AIS_ConnectedInteractive
43         -- -   AIS_MultipleConnectedInteractive
44         -- -   AIS_Shape
45         --   Consequently, 3D presentation should be handled by
46         -- the relevant daughter classes and their member
47         -- functions in AIS. This is particularly true in the
48         -- creation of new interactive objects.
49
50 uses
51     Presentation           from PrsMgr,
52     Presentation           from Prs3d,
53     Presentations          from PrsMgr,
54     PresentationManager    from PrsMgr,
55     PresentationManager3d  from PrsMgr,
56     TypeOfPresentation3d   from PrsMgr,
57     ListOfPresentableObjects from PrsMgr,
58     PresentableObjectPointer from PrsMgr,
59     DataStructureManager   from Graphic3d,
60     Projector              from Prs3d,
61     Transformation         from Geom,
62     ListOfInteger          from TColStd,
63     Location               from TopLoc, 
64     ClipPlane_Handle       from Graphic3d,
65     SequenceOfHClipPlane   from Graphic3d,
66     --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
67     TransModeFlags         from Graphic3d, 
68     Pnt                    from gp,
69     Trsf                   from gp, 
70     CTransPersStruct       from  Graphic3d      
71     --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
72
73 raises
74     NotImplemented from Standard
75 is
76
77
78     Initialize(aTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr = PrsMgr_TOP_AllView);
79       ---C++: alias "Standard_EXPORT virtual ~PrsMgr_PresentableObject();"
80     
81 ---Category: deferred methods.
82 --           
83     
84     Compute(me:mutable;
85                 aPresentationManager: PresentationManager3d from PrsMgr;
86                 aPresentation: Presentation from Prs3d;
87                 aMode: Integer from Standard = 0)
88         ---Purpose: Calculates the 3D view aPresentation and its
89         -- updates. The latter are managed by aPresentationManager.
90         -- aPresentableObject has the display mode aMode;
91         -- this has the default value of 0, that is, the wireframe display mode.
92     raises NotImplemented from Standard
93     is virtual protected;
94     
95     Compute(me            : mutable;
96             aProjector    : Projector from Prs3d;
97             aPresentation  : Presentation from Prs3d)
98         ---Purpose: Calculates the 3D view aPresentation and its
99         -- updates. The latter are managed by
100         -- aPresentationManager. Each of the views in the
101         -- viewer and every modification such as rotation, for
102         -- example, entails recalculation.
103         -- It must be redefined to implement hidden line removal
104         -- for the object. The user never calls this method
105         -- himself. This is done via the InteractiveContext object
106         -- and is dependent on the point of view from which the
107         -- object is displayed.
108     raises NotImplemented from Standard
109     is virtual protected;
110
111     Compute(me            : mutable;
112             aProjector    : Projector from Prs3d;
113             aTrsf         : Transformation from Geom;
114             aPresentation : Presentation from Prs3d)
115     is virtual protected;
116         ---Purpose: Calculates the 3D view aPresentation and its
117         -- updates. The latter are managed by
118         -- aPresentationManager. A point of view is provided
119         -- by the projector aProjector, and the geometric
120         -- transformation which has transformed associated
121         -- presentable objects is specified by aTrsf.
122         -- This function is to be used in case where a hidden
123         -- line removal display cannot be calculated
124         -- automatically. This occurs   when associated
125         -- presentable objects have been transformed
126         -- geometrically, but not translated.
127         -- Warning
128         -- The transformation aTrsf must be applied to the
129         -- object before computation.
130
131     Update(me: mutable;AllModes: Boolean=Standard_False)
132         ---Purpose: recomputes all presentations of the object.
133         ---Level: Public 
134     is protected;
135
136     Update(me: mutable; aMode: Integer from Standard; ClearOther: Boolean from Standard)
137         ---Purpose: Recomputes the presentation in the given mode.
138         --          If ClearOther is true, other presentation will be cleared.
139     is protected;
140     
141     Fill(me: mutable; 
142                 aPresentationManager: PresentationManager from PrsMgr;
143                 aPresentation: Presentation from PrsMgr;
144                 aMode: Integer from Standard = 0)
145     -- 22-03-04 OCC4895 SAN High-level interface for controlling polygon offsets
146     is virtual protected;
147         --- Purpose: High-level interface for controlling polygon offsets
148         
149         -- 22-03-04 OCC4895 SAN High-level interface for controlling polygon offsets
150
151     
152     -- Presentations(me: mutable) returns Presentations from PrsMgr
153     -- is static private;
154     
155     Presentations(me : mutable) returns Presentations from PrsMgr
156     is static;
157         ---C++: return &
158             
159    TypeOfPresentation3d(me) returns TypeOfPresentation3d from PrsMgr
160    is static;
161         ---Purpose: Returns information on whether the object accepts display in HLR mode or not.
162     
163    --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate ) 
164    SetTransformPersistence(  me     :  mutable; 
165                              aFlag  :  TransModeFlags  from  Graphic3d; 
166                              APoint :  Pnt from gp )
167    is virtual; 
168    ---Level:    Public 
169    ---Purpose:  Sets up Transform Persistence Mode for this object.
170    -- This function used to lock in object position, rotation and / or zooming relative to camera position.
171    -- Object will be drawn in the origin setted by APoint parameter (except Graphic3d_TMF_TriedronPers flag
172    -- - see description later). aFlag should be:
173    -- -   Graphic3d_TMF_None - no persistence attributes (reset);
174    -- -   Graphic3d_TMF_PanPers - object doesn't move;
175    -- -   Graphic3d_TMF_ZoomPers - object doesn't resize;
176    -- -   Graphic3d_TMF_RotatePers - object doesn't rotate;
177    -- -   Graphic3d_TMF_FullPers - pan, zoom and rotate transform persistence;
178    -- -   Graphic3d_TMF_TriedronPers - object behaves like trihedron;
179    -- -   combination (Graphic3d_TMF_PanPers | Graphic3d_TMF_ZoomPers);
180    -- -   combination (Graphic3d_TMF_PanPers | Graphic3d_TMF_RotatePers);
181    -- -   combination (Graphic3d_TMF_ZoomPers | Graphic3d_TMF_RotatePers).
182    -- If Graphic3d_TMF_TriedronPers persistence mode selected APoint coordinates X and Y means:
183    -- -   X = 0.0, Y = 0.0 - center of view window;
184    -- -   X > 0.0, Y > 0.0 - right upper corner of view window;
185    -- -   X > 0.0, Y < 0.0 - right lower corner of view window;
186    -- -   X < 0.0, Y > 0.0 - left  upper corner of view window;
187    -- -   X < 0.0, Y < 0.0 - left  lower corner of view window.
188    -- And Z coordinate defines the gap from border of view window (except center position).
189    ---Category: Graphic attributes management  
190    
191    SetTransformPersistence(  me     :  mutable; 
192                              aFlag  :  TransModeFlags  from  Graphic3d ) 
193    is  static; 
194    ---Level:    Public 
195    ---Purpose:  Calls previous method  with  point  (0,0,0)
196    ---Category: Graphic attributes management 
197    
198     
199    GetTransformPersistenceMode( me )  returns  TransModeFlags  from  Graphic3d  is  static;
200     
201    ---Level:    Public 
202    ---Purpose:  Gets  Transform  Persistence Mode  for  this  object 
203    ---Category: Graphic attributes management
204
205    GetTransformPersistencePoint( me )  returns  Pnt  from  gp  is  static;
206     
207    ---Level:    Public 
208    ---Purpose:  Gets  point  of  transform  persistence for  this  object 
209    ---Category: Graphic attributes management
210     
211    --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
212     
213    SetTypeOfPresentation(me:mutable; aType: TypeOfPresentation3d from PrsMgr);    
214
215    SetToUpdate    (me:mutable;aMode:Integer from Standard);
216    ---Purpose: flags the Prs of mode <AMode> to be Updated.
217    --          the Update will be done when needed.
218    
219    SetToUpdate(me:mutable); 
220    ---Purpose: flags all the Presentations to be Updated.
221     
222    ToBeUpdated(me;ListOfMode : out ListOfInteger from TColStd);
223    ---Purpose: gives the list of modes which are flagged "to be updated".
224     
225    SetLocalTransformation(me:mutable; theTransformation:Trsf from gp) is virtual;
226    ---Purpose: Sets local transformation to theTransformation.
227
228    SetCombinedParentTransform(me:mutable; theTransformation:Trsf from gp) is virtual protected;
229    ---Purpose: Sets myCombinedParentTransform to theTransformation. Thus object receives transformation
230    -- from parent node and able to derive its own.
231     
232    HasTransformation(me) returns Boolean from Standard;
233    ---Purpose: Returns true if object has a transformation that is different from the identity.
234    
235    LocalTransformation(me) returns any Trsf from gp;
236    ---C++: inline
237    ---C++: return const&
238
239    Transformation(me) returns any Trsf from gp;
240    ---C++: inline
241    ---C++: return const&
242    
243    ResetTransformation(me:mutable)  is virtual;
244    ---Purpose: resets local transformation to identity.
245
246    UpdateTransformation(me:mutable) is virtual;
247     
248    UpdateTransformation(me:mutable;P : Presentation from Prs3d) is virtual;
249     
250    SetZLayer ( me         : mutable;
251                thePrsMgr  : PresentationManager from PrsMgr;
252                theLayerId : Integer from Standard )
253      is virtual;
254    ---Purpose: Set Z layer ID and update all presentations of
255    -- the presentable object. The layer can be set only for displayed object.
256    -- If all object presentations are removed, the layer ID will be set to 
257    -- default value when computing presentation. The layers mechanism allows
258    -- drawing objects in higher layers in overlay of objects in lower layers.
259     
260    GetZLayer ( me;
261                thePrsMgr  : PresentationManager from PrsMgr )
262      returns Integer from Standard is static;
263    ---Purpose: Get ID of Z layer. If no presentations of object is displayed,
264    -- and layer ID is unavailable, the -1 value is returned.
265
266    AddClipPlane (me : mutable; thePlane : ClipPlane_Handle from Graphic3d) is virtual;
267    ---Purpose: Adds clip plane for graphical clipping for all display mode
268    -- presentations. The composition of clip planes truncates the rendering
269    -- space to convex volume. Please be aware that number of supported
270    -- clip plane is limited. The planes which exceed the limit are ignored.
271    -- Besides of this, some planes can be already set in view where the object
272    -- is shown: the number of these planes should be substracted from limit
273    -- to predict the maximum possible number of object clipping planes.
274    -- @param thePlane [in] the clip plane to be appended to map of clip planes.
275
276    RemoveClipPlane (me : mutable; thePlane : ClipPlane_Handle from Graphic3d) is virtual;
277    ---Purpose: Removes previously added clip plane.
278    -- @param thePlane [in] the clip plane to be removed from map of clip planes.
279
280    SetClipPlanes (me : mutable; thePlanes : SequenceOfHClipPlane from Graphic3d) is virtual;
281    ---Purpose: Set clip planes for graphical clipping for all display mode presentations.
282    -- The composition of clip planes truncates the rendering space to convex
283    -- volume. Please be aware that number of supported clip plane is limited.
284    -- The planes which exceed the limit are ignored. Besides of this, some
285    -- planes can be already set in view where the object is shown: the number 
286    -- of these planes should be substracted from limit to predict the maximum
287    -- possible number of object clipping planes.
288
289    GetClipPlanes (me) returns SequenceOfHClipPlane from Graphic3d;
290    ---C++: inline
291    ---C++: return const&
292    ---Purpose: Get clip planes.
293    -- @return set of previously added clip planes for all display mode presentations.
294
295   SetMutable ( me           : mutable;
296                theIsMutable : Boolean from Standard ) is virtual;
297   ---Purpose: Sets if the object has mutable nature (content or location will be changed regularly).
298   -- This method should be called before object displaying to take effect.
299
300   IsMutable (me) returns Boolean from Standard;
301   ---C++: return const
302   ---Purpose: Returns true if object has mutable nature (content or location are be changed regularly).
303   -- Mutable object will be managed in different way than static onces (another optimizations).
304
305   AddChild ( me           : mutable;
306              theObject    : PresentableObject from PrsMgr ) is virtual;
307     --- Purpose: Makes theObject child of current object in scene hierarchy. 
308
309   RemoveChild ( me           : mutable;
310                 theObject    : PresentableObject from PrsMgr ) is virtual;
311     --- Purpose: Removes theObject from children of current object in scene hierarchy. 
312
313   Children (me) returns ListOfPresentableObjects from PrsMgr is static;
314     ---C++: return const&
315     --- Purpose: Returns children of the current object.
316
317   HasOwnPresentations (me) returns Boolean from Standard is static;
318     ---C++: return const
319     --- Purpose: Returns true if object should have own presentations.
320
321   Parent (me) returns PresentableObjectPointer from PrsMgr is static;
322     ---C++: return const
323     --- Purpose: Returns parent of current object in scene hierarchy.
324
325    UpdateClipping (me : mutable) is virtual protected;
326    ---Purpose: General virtual method for internal update of presentation state
327    -- when some modifications on list of clip planes occurs. Base 
328    -- implementation propagate clip planes to every presentation.
329
330 fields
331     myPresentations: Presentations from PrsMgr is protected;
332     myTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr is protected;
333     myClipPlanes : SequenceOfHClipPlane from Graphic3d is protected;
334     myTransformPersistence  :  CTransPersStruct  from  Graphic3d;
335     myIsMutable : Boolean from Standard is protected;
336
337
338     myHasOwnPresentations : Boolean from Standard is protected; -- shows if object should have own presentations.
339
340     myParent : PresentableObjectPointer from PrsMgr; -- Reference to parent object in scene hierarchy.
341  
342     myLocalTransformation : Trsf from gp;     -- Own transformation of presentable object.
343     myTransformation : Trsf from gp;          -- Combined transformation of presentable object.
344     myCombinedParentTransform : Trsf from gp; -- Combined transformation of presentable object excepting local transformation.
345
346     myChildren : ListOfPresentableObjects from PrsMgr; -- Child objects in scene hierarchy.
347
348 friends
349     class Presentation        from PrsMgr,
350     class PresentationManager from PrsMgr,
351     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d),
352     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
353                                                         aGivenStruct :  Structure from Graphic3d),
354     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
355                                                         TheTrsf   : Transformation from Geom),
356     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
357                                                         TheTrsf      : Transformation from Geom;
358                                                         aGivenStruct : Structure from Graphic3d)
359 end PresentableObject from PrsMgr;