9b88fe54fff6100a5fe7ece4f4963102d651d963
[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     DataStructureManager  from Graphic3d,
58     Projector             from Prs3d,
59     Transformation        from Geom,
60     ListOfInteger         from TColStd,
61     Location              from TopLoc, 
62     ClipPlane_Handle      from Graphic3d,
63     SequenceOfHClipPlane  from Graphic3d,
64     --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
65     TransModeFlags        from Graphic3d, 
66     Pnt                   from gp, 
67     CTransPersStruct      from  Graphic3d      
68     --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
69
70 raises
71     NotImplemented from Standard
72 is
73
74
75     Initialize(aTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr = PrsMgr_TOP_AllView);
76     
77 ---Category: deferred methods.
78 --           
79     
80     Compute(me:mutable;
81                 aPresentationManager: PresentationManager3d from PrsMgr;
82                 aPresentation: Presentation from Prs3d;
83                 aMode: Integer from Standard = 0)
84         ---Purpose: Calculates the 3D view aPresentation and its
85         -- updates. The latter are managed by aPresentationManager.
86         -- aPresentableObject has the display mode aMode;
87         -- this has the default value of 0, that is, the wireframe display mode.
88     raises NotImplemented from Standard
89     is virtual protected;
90     
91     Compute(me            : mutable;
92             aProjector    : Projector from Prs3d;
93             aPresentation  : Presentation from Prs3d)
94         ---Purpose: Calculates the 3D view aPresentation and its
95         -- updates. The latter are managed by
96         -- aPresentationManager. Each of the views in the
97         -- viewer and every modification such as rotation, for
98         -- example, entails recalculation.
99         -- It must be redefined to implement hidden line removal
100         -- for the object. The user never calls this method
101         -- himself. This is done via the InteractiveContext object
102         -- and is dependent on the point of view from which the
103         -- object is displayed.
104     raises NotImplemented from Standard
105     is virtual protected;
106
107     Compute(me            : mutable;
108             aProjector    : Projector from Prs3d;
109             aTrsf         : Transformation from Geom;
110             aPresentation : Presentation from Prs3d)
111     is virtual protected;
112         ---Purpose: Calculates the 3D view aPresentation and its
113         -- updates. The latter are managed by
114         -- aPresentationManager. A point of view is provided
115         -- by the projector aProjector, and the geometric
116         -- transformation which has transformed associated
117         -- presentable objects is specified by aTrsf.
118         -- This function is to be used in case where a hidden
119         -- line removal display cannot be calculated
120         -- automatically. This occurs   when associated
121         -- presentable objects have been transformed
122         -- geometrically, but not translated.
123         -- Warning
124         -- The transformation aTrsf must be applied to the
125         -- object before computation.
126
127     Update(me: mutable;AllModes: Boolean=Standard_False)
128         ---Purpose: recomputes all presentations of the object.
129         ---Level: Public 
130     is protected;
131
132     Update(me: mutable; aMode: Integer from Standard; ClearOther: Boolean from Standard)
133         ---Purpose: Recomputes the presentation in the given mode.
134         --          If ClearOther is true, other presentation will be cleared.
135     is protected;
136     
137     Fill(me: mutable; 
138                 aPresentationManager: PresentationManager from PrsMgr;
139                 aPresentation: Presentation from PrsMgr;
140                 aMode: Integer from Standard = 0)
141     -- 22-03-04 OCC4895 SAN High-level interface for controlling polygon offsets
142     is virtual protected;
143         --- Purpose: High-level interface for controlling polygon offsets
144         
145         -- 22-03-04 OCC4895 SAN High-level interface for controlling polygon offsets
146
147     
148     -- Presentations(me: mutable) returns Presentations from PrsMgr
149     -- is static private;
150     
151     Presentations(me : mutable) returns Presentations from PrsMgr
152     is static protected;
153         ---C++: return &
154             
155    TypeOfPresentation3d(me) returns TypeOfPresentation3d from PrsMgr
156    is static;
157         ---Purpose: Returns information on whether the object accepts display in HLR mode or not.
158     
159    --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate ) 
160    SetTransformPersistence(  me     :  mutable; 
161                              aFlag  :  TransModeFlags  from  Graphic3d; 
162                              APoint :  Pnt from gp )
163    is virtual; 
164    ---Level:    Public 
165    ---Purpose:  Sets up Transform Persistence Mode for this object.
166    -- This function used to lock in object position, rotation and / or zooming relative to camera position.
167    -- Object will be drawn in the origin setted by APoint parameter (except Graphic3d_TMF_TriedronPers flag
168    -- - see description later). aFlag should be:
169    -- -   Graphic3d_TMF_None - no persistence attributes (reset);
170    -- -   Graphic3d_TMF_PanPers - object doesn't move;
171    -- -   Graphic3d_TMF_ZoomPers - object doesn't resize;
172    -- -   Graphic3d_TMF_RotatePers - object doesn't rotate;
173    -- -   Graphic3d_TMF_FullPers - pan, zoom and rotate transform persistence;
174    -- -   Graphic3d_TMF_TriedronPers - object behaves like trihedron;
175    -- -   combination (Graphic3d_TMF_PanPers | Graphic3d_TMF_ZoomPers);
176    -- -   combination (Graphic3d_TMF_PanPers | Graphic3d_TMF_RotatePers);
177    -- -   combination (Graphic3d_TMF_ZoomPers | Graphic3d_TMF_RotatePers).
178    -- If Graphic3d_TMF_TriedronPers persistence mode selected APoint coordinates X and Y means:
179    -- -   X = 0.0, Y = 0.0 - center of view window;
180    -- -   X > 0.0, Y > 0.0 - right upper corner of view window;
181    -- -   X > 0.0, Y < 0.0 - right lower corner of view window;
182    -- -   X < 0.0, Y > 0.0 - left  upper corner of view window;
183    -- -   X < 0.0, Y < 0.0 - left  lower corner of view window.
184    -- And Z coordinate defines the gap from border of view window (except center position).
185    ---Category: Graphic attributes management  
186    
187    SetTransformPersistence(  me     :  mutable; 
188                              aFlag  :  TransModeFlags  from  Graphic3d ) 
189    is  static; 
190    ---Level:    Public 
191    ---Purpose:  Calls previous method  with  point  (0,0,0)
192    ---Category: Graphic attributes management 
193    
194     
195    GetTransformPersistenceMode( me )  returns  TransModeFlags  from  Graphic3d  is  static;
196     
197    ---Level:    Public 
198    ---Purpose:  Gets  Transform  Persistence Mode  for  this  object 
199    ---Category: Graphic attributes management
200
201    GetTransformPersistencePoint( me )  returns  Pnt  from  gp  is  static;
202     
203    ---Level:    Public 
204    ---Purpose:  Gets  point  of  transform  persistence for  this  object 
205    ---Category: Graphic attributes management
206     
207    --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
208     
209    SetTypeOfPresentation(me:mutable; aType: TypeOfPresentation3d from PrsMgr);    
210
211    SetToUpdate    (me:mutable;aMode:Integer from Standard);
212    ---Purpose: flags the Prs of mode <AMode> to be Updated.
213    --          the Update will be done when needed.
214    
215    SetToUpdate(me:mutable); 
216    ---Purpose: flags all the Presentations to be Updated.
217     
218    ToBeUpdated(me;ListOfMode : out ListOfInteger from TColStd);
219    ---Purpose: gives the list of modes which are flagged "to be updated".
220     
221    SetLocation(me:mutable;aLoc:Location from TopLoc) is virtual;
222     
223    HasLocation(me) returns Boolean from Standard;
224    
225    Location(me) returns any Location from TopLoc;
226    ---C++: inline
227    ---C++: return const&
228    
229    ResetLocation(me:mutable)  is virtual;
230
231    UpdateLocation(me:mutable) is virtual;
232     
233    UpdateLocation(me:mutable;P : Presentation from Prs3d) is virtual;
234     
235    SetZLayer ( me         : mutable;
236                thePrsMgr  : PresentationManager from PrsMgr;
237                theLayerId : Integer from Standard )
238      is virtual;
239    ---Purpose: Set Z layer ID and update all presentations of
240    -- the presentable object. The layer can be set only for displayed object.
241    -- If all object presentations are removed, the layer ID will be set to 
242    -- default value when computing presentation. The layers mechanism allows
243    -- drawing objects in higher layers in overlay of objects in lower layers.
244     
245    GetZLayer ( me;
246                thePrsMgr  : PresentationManager from PrsMgr )
247      returns Integer from Standard is static;
248    ---Purpose: Get ID of Z layer. If no presentations of object is displayed,
249    -- and layer ID is unavailable, the -1 value is returned.
250
251    AddClipPlane (me : mutable; thePlane : ClipPlane_Handle from Graphic3d) is virtual;
252    ---Purpose: Adds clip plane for graphical clipping for all display mode
253    -- presentations. The composition of clip planes truncates the rendering
254    -- space to convex volume. Please be aware that number of supported
255    -- clip plane is limited. The planes which exceed the limit are ignored.
256    -- Besides of this, some planes can be already set in view where the object
257    -- is shown: the number of these planes should be substracted from limit
258    -- to predict the maximum possible number of object clipping planes.
259    -- @param thePlane [in] the clip plane to be appended to map of clip planes.
260
261    RemoveClipPlane (me : mutable; thePlane : ClipPlane_Handle from Graphic3d) is virtual;
262    ---Purpose: Removes previously added clip plane.
263    -- @param thePlane [in] the clip plane to be removed from map of clip planes.
264
265    SetClipPlanes (me : mutable; thePlanes : SequenceOfHClipPlane from Graphic3d) is virtual;
266    ---Purpose: Set clip planes for graphical clipping for all display mode presentations.
267    -- The composition of clip planes truncates the rendering space to convex
268    -- volume. Please be aware that number of supported clip plane is limited.
269    -- The planes which exceed the limit are ignored. Besides of this, some
270    -- planes can be already set in view where the object is shown: the number 
271    -- of these planes should be substracted from limit to predict the maximum
272    -- possible number of object clipping planes.
273
274    GetClipPlanes (me) returns SequenceOfHClipPlane from Graphic3d;
275    ---C++: inline
276    ---C++: return const&
277    ---Purpose: Get clip planes.
278    -- @return set of previously added clip planes for all display mode presentations.
279
280   SetMutable ( me           : mutable;
281                theIsMutable : Boolean from Standard ) is virtual;
282   ---Purpose: Sets if the object has mutable nature (content or location will be changed regularly).
283   -- This method should be called before object displaying to take effect.
284
285   IsMutable (me) returns Boolean from Standard;
286   ---C++: return const
287   ---Purpose: Returns true if object has mutable nature (content or location are be changed regularly).
288   -- Mutable object will be managed in different way than static onces (another optimizations).
289
290    UpdateClipping (me : mutable) is virtual protected;
291    ---Purpose: General virtual method for internal update of presentation state
292    -- when some modifications on list of clip planes occurs. Base 
293    -- implementation propagate clip planes to every presentation.
294
295 fields
296     myPresentations: Presentations from PrsMgr is protected;
297     myTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr is protected;
298     myLocation  : Location from TopLoc is protected; 
299     myClipPlanes : SequenceOfHClipPlane from Graphic3d is protected;
300     myTransformPersistence  :  CTransPersStruct  from  Graphic3d;
301     myIsMutable : Boolean from Standard is protected;
302
303 friends
304     class Presentation        from PrsMgr,
305     class PresentationManager from PrsMgr,
306     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d),
307     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
308                                                         aGivenStruct :  Structure from Graphic3d),
309     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
310                                                         TheTrsf   : Transformation from Geom),
311     Compute from Presentation from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
312                                                         TheTrsf      : Transformation from Geom;
313                                                         aGivenStruct : Structure from Graphic3d)
314 end PresentableObject from PrsMgr;