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;