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-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21 -- Modified by  Rob (18/12/96) -> information about modes to update.
  22 --              Rob (04/07/97) ->   TypeOfPresentation3d () Method
  23 --                                  changed to Public Method.
  24 --                             -> Option Projector Dependant/Independant
  25 --                                may be set at any time , not only in
  26 --                                the constructor or the presentable.
  27 --                               ->Insert Locations Methods...
  28 --              Rob (16/12/97) -> Get the list of modes to be updated
  29 --                             -> Flags all the Prs to be updated...
  30 --              GG IMP020200   -> Presentations() method become protected
  31 --                              and no more private.
  32 --              SAN (22/03/04) -> OCC4895 High-level interface for controlling
  33 --                              polygon offsets: Fill() made protected virtual.
  34
  35 deferred class PresentableObject from PrsMgr inherits TShared from MMgt
  36
  37
  38         ---Purpose: A framework to supply the Graphic3d
  39         -- structure of the object to be presented. On the first
  40         -- display request, this structure is created by calling the
  41         -- appropriate algorithm and retaining this frameworkfor
  42         -- further display.
  43         -- This abstract framework is inherited in Application
  44         -- Interactive Services (AIS), notably in:
  45         -- -   AIS_InteractiveObject
  46         -- -   AIS_ConnectedInteractive
  47         -- -   AIS_MultipleConnectedInteractive
  48         -- -   AIS_Shape
  49         --   Consequently, 3D presentation should be handled by
  50         -- the relevant daughter classes and their member
  51         -- functions in AIS. This is particularly true in the
  52         -- creation of new interactive objects.
  53
  54 uses
  55     Presentation          from PrsMgr,
  56     Presentation          from Prs3d,
  57     Presentations         from PrsMgr,
  58     PresentationManager   from PrsMgr,
  59     PresentationManager3d from PrsMgr,
  60     TypeOfPresentation3d  from PrsMgr,
  61     DataStructureManager  from Graphic3d,
  62     Projector             from Prs3d,
  63     Transformation        from Geom,
  64     ListOfInteger         from TColStd,
  65     Location              from TopLoc,
  66     ClipPlane_Handle      from Graphic3d,
  67     SequenceOfHClipPlane  from Graphic3d,
  68     --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
  69     TransModeFlags        from Graphic3d,
  70     Pnt                   from gp,
  71     CTransPersStruct      from  Graphic3d
  72     --   ABD 29/10/04  Transform Persistence of Presentation( pan, zoom, rotate )
  73
  74 raises
  75     NotImplemented from Standard
  76 is
  77
  78
  79     Initialize(aTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr = PrsMgr_TOP_AllView);
  80
  81 ---Category: deferred methods.
  82 --
  83
  84     Compute(me:mutable;
  85                 aPresentationManager: PresentationManager3d from PrsMgr;
  86                 aPresentation: mutable 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  : mutable 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 : mutable 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: mutable 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 protected;
 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    SetLocation(me:mutable;aLoc:Location from TopLoc) is virtual;
 226
 227    HasLocation(me) returns Boolean from Standard;
 228
 229    Location(me) returns any Location from TopLoc;
 230    ---C++: inline
 231    ---C++: return const&
 232
 233    ResetLocation(me:mutable)  is virtual;
 234
 235    UpdateLocation(me:mutable) is virtual;
 236
 237    UpdateLocation(me:mutable;P : mutable Presentation from Prs3d) is virtual;
 238
 239    SetZLayer ( me         : mutable;
 240                thePrsMgr  : PresentationManager from PrsMgr;
 241                theLayerId : Integer from Standard )
 242      is virtual;
 243    ---Purpose: Set Z layer ID and update all presentations of
 244    -- the presentable object. The layer can be set only for displayed object.
 245    -- If all object presentations are removed, the layer ID will be set to
 246    -- default value when computing presentation. The layers mechanism allows
 247    -- drawing objects in higher layers in overlay of objects in lower layers.
 248
 249    GetZLayer ( me;
 250                thePrsMgr  : PresentationManager from PrsMgr )
 251      returns Integer from Standard is static;
 252    ---Purpose: Get ID of Z layer. If no presentations of object is displayed,
 253    -- and layer ID is unavailable, the -1 value is returned.
 254
 255    AddClipPlane (me : mutable; thePlane : ClipPlane_Handle from Graphic3d) is virtual;
 256    ---Purpose: Adds clip plane for graphical clipping for all display mode
 257    -- presentations. The composition of clip planes truncates the rendering
 258    -- space to convex volume. Please be aware that number of supported
 259    -- clip plane is limited. The planes which exceed the limit are ignored.
 260    -- Besides of this, some planes can be already set in view where the object
 261    -- is shown: the number of these planes should be substracted from limit
 262    -- to predict the maximum possible number of object clipping planes.
 263    -- @param thePlane [in] the clip plane to be appended to map of clip planes.
 264
 265    RemoveClipPlane (me : mutable; thePlane : ClipPlane_Handle from Graphic3d) is virtual;
 266    ---Purpose: Removes previously added clip plane.
 267    -- @param thePlane [in] the clip plane to be removed from map of clip planes.
 268
 269    SetClipPlanes (me : mutable; thePlanes : SequenceOfHClipPlane from Graphic3d) is virtual;
 270    ---Purpose: Set clip planes for graphical clipping for all display mode presentations.
 271    -- The composition of clip planes truncates the rendering space to convex
 272    -- volume. Please be aware that number of supported clip plane is limited.
 273    -- The planes which exceed the limit are ignored. Besides of this, some
 274    -- planes can be already set in view where the object is shown: the number
 275    -- of these planes should be substracted from limit to predict the maximum
 276    -- possible number of object clipping planes.
 277
 278    GetClipPlanes (me) returns SequenceOfHClipPlane from Graphic3d;
 279    ---C++: inline
 280    ---C++: return const&
 281    ---Purpose: Get clip planes.
 282    -- @return set of previously added clip planes for all display mode presentations.
 283
 284    UpdateClipping (me : mutable) is virtual protected;
 285    ---Purpose: General virtual method for internal update of presentation state
 286    -- when some modifications on list of clip planes occurs. Base
 287    -- implementation propagate clip planes to every presentation.
 288
 289 fields
 290     myPresentations: Presentations from PrsMgr is protected;
 291     myTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr is protected;
 292     myLocation  : Location from TopLoc is protected;
 293     myClipPlanes : SequenceOfHClipPlane from Graphic3d is protected;
 294     --myTransformPersistence  :  TransModeFlags  from  Graphic3d;
 295     myTransformPersistence  :  CTransPersStruct  from  Graphic3d;
 296
 297 friends
 298     class Presentation3d      from PrsMgr,
 299     class PresentationManager from PrsMgr,
 300     Compute from Presentation3d from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d),
 301     Compute from Presentation3d from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
 302                                                           aGivenStruct :  Structure from Graphic3d),
 303     Compute from Presentation3d from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
 304                                                           TheTrsf   : Transformation from Geom),
 305     Compute from Presentation3d from PrsMgr(me : mutable; aProjector   : DataStructureManager from Graphic3d;
 306                                                           TheTrsf      : Transformation from Geom;
 307                                                           aGivenStruct : Structure from Graphic3d)
 308 end PresentableObject from PrsMgr;