src/Graphic3d/Graphic3d_Structure.cdl

   1 -- Created on: 1991-06-12
   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 --              11/97 ; CAL : ajout pointer StructPtr
  19 --              11/97 ; CAL : amelioration de l'effacement SetManager
  20 --              01/98 ; CAL : gestion du HLRValidation
  21 --              05/98 ; CAL : gestion du GraphicConnect et Disconnect
  22 --              02/00 ; GG  : Made Transform() methode not mutable.
  23 --              31/05/01 ; GG : Add ResetDisplayPriority() method
  24
  25 class Structure from Graphic3d inherits TShared
  26
  27         ---Version:
  28
  29         ---Purpose: This class allows the definition a graphic object.
  30         --          This graphic structure can be displayed,
  31         --          erased, or highlighted.
  32         --          This graphic structure can be connected with
  33         --          another graphic structure.
  34         --  Keywords: Structure, StructureManager, Display, Erase, Highlight,
  35         --           UnHighlight, Visible, Priority, Selectable, Visible,
  36         --           Visual, Connection, Ancestors, Descendants, Transformation
  37
  38         ---Warning:
  39         ---References:
  40
  41 uses
  42
  43         Array2OfReal            from TColStd,
  44         SequenceOfAddress       from TColStd,
  45
  46         Color                   from Quantity,
  47
  48         GenId                   from Aspect,
  49         TypeOfHighlightMethod   from Aspect,
  50
  51         DataStructureManager    from Graphic3d,
  52         AspectFillArea3d        from Graphic3d,
  53         AspectLine3d            from Graphic3d,
  54         AspectMarker3d          from Graphic3d,
  55         AspectText3d            from Graphic3d,
  56         CStructure          from Graphic3d,
  57         CStructure_Handle   from Graphic3d,
  58         GraphicDriver           from Graphic3d,
  59         Group                   from Graphic3d,
  60         SequenceOfGroup         from Graphic3d,
  61         SequenceOfStructure     from Graphic3d,
  62         HSequenceOfStructure    from Graphic3d,
  63         MapOfStructure          from Graphic3d,
  64         StructureManager        from Graphic3d,
  65         StructureManagerPtr from Graphic3d,
  66         TypeOfComposition       from Graphic3d,
  67         TypeOfConnection        from Graphic3d,
  68         TypeOfPrimitive         from Graphic3d,
  69         TypeOfStructure         from Graphic3d,
  70         Vector                  from Graphic3d,
  71         Vertex                  from Graphic3d,
  72         TransModeFlags          from Graphic3d,
  73         Pnt                     from gp,
  74     SequenceOfHClipPlane from Graphic3d,
  75     BndBox4f from Graphic3d,
  76     BndBox4d from Graphic3d,
  77     Box from Bnd
  78
  79 raises
  80
  81         PriorityDefinitionError         from Graphic3d,
  82         StructureDefinitionError        from Graphic3d,
  83         TransformError                  from Graphic3d
  84
  85 is
  86
  87         ------------------------
  88         -- Category: Constructor
  89         ------------------------
  90
  91   Create (theManager : StructureManager from Graphic3d)
  92   returns Structure from Graphic3d;
  93   ---Level: Public
  94   ---Purpose: Creates a graphic object in the manager theManager.
  95   -- It will appear in all the views of the visualiser.
  96   -- Warning: The default values AspectLine, AspectFillArea, AspectText and AspectMarker are NOT applied to the structure.
  97   -- The structure is not displayed when it is created.
  98
  99   Create (theManager : StructureManager from Graphic3d;
 100           thePrs     : Structure        from Graphic3d)
 101   returns Structure from Graphic3d;
 102   ---Level: Public
 103   ---Purpose: Creates a shadow link to existing graphic object.
 104
 105         ---------------------------------------------------
 106         -- Category: Methods to modify the class definition
 107         ---------------------------------------------------
 108
 109         --------------------------------------------------------
 110         -- Summary of Display Priorities                      --
 111         --                                                    --
 112         -- Structure display priorities  control the order in --
 113         -- which structures are redrawn.                      --
 114         --                                                    --
 115         -- When  you  display  a structure, you  specify  its --
 116         -- priority.  The  lower  the  value, the  lower  the --
 117         -- display priority. When the display is regenerated, --
 118         -- the structures  with the lowest priority are drawn --
 119         -- first.                                             --
 120         -- For  structures  with the  same display  priority, --
 121         -- the  order in which they were displayed determines --
 122         -- determines the drawing order.                      --
 123         --                                                    --
 124         -- CAS.CADE supports 11 structure display priorities, --
 125         -- 0 to 10.                                           --
 126         --------------------------------------------------------
 127
 128         Clear ( me              : mutable;
 129                 WithDestruction : Boolean from Standard = Standard_True )
 130                 is virtual;
 131         ---Level: Public
 132         ---Purpose: if WithDestruction == Standard_True then
 133         --              suppress all the groups of primitives in the structure.
 134         --              and it is mandatory to create a new group in <me>.
 135         --          if WithDestruction == Standard_False then
 136         --              clears all the groups of primitives in the structure.
 137         --              and all the groups are conserved and empty.
 138         --          They will be erased at the next screen update.
 139         --          The structure itself is conserved.
 140         --          The transformation and the attributes of <me> are conserved.
 141         --          The childs of <me> are conserved.
 142         ---Category: Methods to modify the class definition
 143
 144         Destroy ( me    : mutable )
 145                 is virtual;
 146         ---Level: Public
 147         ---Purpose: Suppresses the structure <me>.
 148         --          It will be erased at the next screen update.
 149         ---Category: Methods to modify the class definition
 150         ---C++: alias ~
 151
 152         Display ( me    : mutable )
 153                 is virtual;
 154         ---Level: Public
 155         ---Purpose: Displays the structure <me> in all the views of
 156         --          the visualiser.
 157         ---Category: Methods to modify the class definition
 158
 159         Display ( me            : mutable;
 160                   Priority      : Integer from Standard )
 161         ---Level: Public
 162         ---Purpose: Displays the structure <me> in all the views of
 163         --          the visualiser, while modifying its current priority.
 164         --          Note: Display Priorities
 165         --          Structure display priorities control the order in which
 166         --          structures are redrawn.   When you display a
 167         --          structure, you specify its priority. The lower the value,
 168         --          the lower the display priority. When the display is
 169         --          regenerated, the structures with the lowest priority
 170         --          are drawn first. For structures with the same display
 171         --          priority, the order in which they were displayed
 172         --          determines the drawing order. Open CASCADE
 173         --          supports 11 structure display priorities, 0 to 10.
 174         --          Warning: Raises PriorityDefinitionError if <Priority> is
 175         --          greater than 10 or a negative value.
 176         raises PriorityDefinitionError from Graphic3d is static;
 177
 178         DisplayPriority ( me )
 179                 returns Integer from Standard
 180                 is static;
 181         ---Level: Public
 182         ---Purpose: Returns the current display priority for the
 183         --          structure <me>.
 184         ---Category: Methods to modify the class definition
 185
 186         Erase ( me      : mutable )
 187                 is virtual;
 188         ---Level: Public
 189         ---Purpose: Erases the structure <me> in all the views
 190         --          of the visualiser.
 191         ---Category: Methods to modify the class definition
 192
 193         Highlight ( me          : mutable;
 194                     Method      : TypeOfHighlightMethod from Aspect )
 195                 is static;
 196         ---Level: Public
 197         ---Purpose: Highlights the structure <me> in all the
 198         --          views of the visualiser, using the following methods:
 199         --
 200         --   TOHM_COLOR         = drawn in the highlight color
 201         --                                (default white)
 202         --          TOHM_BLINK          = blinking
 203         --   TOHM_BOUNDBOX      = enclosed by the boundary box
 204         --                                (default white)
 205         --
 206         ---Category: Methods to modify the class definition
 207
 208         Remove ( me     : mutable )
 209                 is static;
 210         ---Level: Public
 211         ---Purpose: Suppress the structure <me>.
 212         --          It will be erased at the next screen update.
 213         --  Warning: No more graphic operations in <me> after this call.
 214         --  Category: Methods to modify the class definition
 215
 216         CalculateBoundBox ( me  : mutable )
 217                 is static;
 218         ---Level:   Public
 219         ---Purpose: Computes axis-aligned bounding box of a structure.
 220         --  Category: Methods to modify the class definition
 221
 222         SetHighlightColor ( me          : mutable;
 223                             AColor      : Color from Quantity )
 224                 is static;
 225         ---Level: Public
 226         ---Purpose: Modifies the highlight color for the Highlight method
 227         --          with the highlight method TOHM_COLOR or TOHM_BOUNDBOX.
 228         ---Category: Methods to modify the class definition
 229
 230     SetInfiniteState (me : mutable; theToSet : Boolean from Standard) is static;
 231     ---Level: Internal
 232     ---Purpose: If <theToSet> is Standard_True then <me> is infinite and
 233     --          the MinMaxValues method method return :
 234     --          theXMin = theYMin = theZMin = RealFirst().
 235     --          theXMax = theYMax = theZMax = RealLast().
 236     --          By default, <me> is not infinite but empty.
 237     ---Category: Methods to modify the class definition
 238
 239         SetDisplayPriority ( me         : mutable;
 240                              Priority   : Integer from Standard )
 241         ---Level: Public
 242         ---Purpose: Modifies the order of displaying the structure.
 243         --          Values are between 0 and 10.
 244         --          Structures are drawn according to their display priorities
 245         --          in ascending order.
 246         --          A structure of priority 10 is displayed the last and appears over the others.
 247         --          The default value is 5.
 248         --  Category: Methods to modify the class definition
 249         --  Warning: If <me> is displayed then the SetDisplayPriority
 250         --          method erase <me> and display <me> with the
 251         --          new priority.
 252         --          Raises PriorityDefinitionError if <Priority> is
 253         --          greater than 10 or a negative value.
 254         raises PriorityDefinitionError from Graphic3d is static;
 255
 256         ResetDisplayPriority ( me               : mutable)
 257                 is static;
 258         ---Level: Public
 259         ---Purpose: Reset the current priority of the structure to the
 260         --          previous priority.
 261         --  Category: Methods to modify the class definition
 262         --  Warning: If <me> is displayed then the SetDisplayPriority
 263         --          method erase <me> and display <me> with the
 264         --          previous priority.
 265
 266         SetZLayer ( me         : mutable;
 267                     theLayerId : Integer from Standard )
 268            is static;
 269         ---Purpose: Set Z layer ID for the structure. The Z layer mechanism
 270         -- allows to display structures presented in higher layers in overlay
 271         -- of structures in lower layers by switching off z buffer depth
 272         -- test between layers
 273
 274         GetZLayer ( me )
 275           returns Integer from Standard is static;
 276         ---Purpose: Get Z layer ID of displayed structure. The method
 277         -- returns -1 if the structure has no ID (deleted from graphic driver).
 278
 279     SetClipPlanes (me : mutable; thePlanes : SequenceOfHClipPlane from Graphic3d) is static;
 280     ---Purpose: Changes a sequence of clip planes slicing the structure on rendering.
 281     -- @param thePlanes [in] the set of clip planes.
 282
 283     GetClipPlanes (me) returns SequenceOfHClipPlane from Graphic3d;
 284     ---C++: return const&
 285     ---Purpose: Get clip planes slicing the structure on rendering.
 286     -- @return set of clip planes.
 287
 288         SetPick ( me            : mutable;
 289                   AValue        : Boolean from Standard )
 290                 is static;
 291         ---Level: Public
 292         ---Purpose: Modifies the detectability indicator to Standard_True
 293         --          or Standard_False for the structure <me>.
 294         --          The default value at the definition of <me> is
 295         --          Standard_True.
 296         ---Category: Methods to modify the class definition
 297
 298         SetPrimitivesAspect ( me        : mutable;
 299                               CTX       : AspectLine3d from Graphic3d )
 300                 is static;
 301         ---Level: Public
 302         ---Purpose: Modifies the default attributes for lines
 303         --          in the structure <me>.
 304         ---Category: Methods to modify the class definition
 305
 306         SetPrimitivesAspect ( me        : mutable;
 307                               CTX       : AspectFillArea3d from Graphic3d )
 308                 is static;
 309         ---Level: Public
 310         ---Purpose: Modifies the default attributes for faces
 311         --          in the structure <me>.
 312         ---Category: Methods to modify the class definition
 313
 314         SetPrimitivesAspect ( me        : mutable;
 315                               CTX       : AspectText3d from Graphic3d )
 316                 is static;
 317         ---Level: Public
 318         ---Purpose: Modifies the default attributes for text
 319         --          in the structure <me>.
 320         ---Category: Methods to modify the class definition
 321
 322         SetPrimitivesAspect ( me        : mutable;
 323                               CTX       : AspectMarker3d from Graphic3d )
 324                 is static;
 325         ---Level: Public
 326         ---Purpose: Modifies the default attributes for markers
 327         --          in the structure <me>.
 328         ---Category: Methods to modify the class definition
 329
 330         SetVisible ( me         : mutable;
 331                      AValue     : Boolean from Standard )
 332                 is static;
 333         ---Level: Public
 334         ---Purpose: Modifies the visibility indicator to Standard_True or
 335         --          Standard_False for the structure <me>.
 336         --          The default value at the definition of <me> is
 337         --          Standard_True.
 338         ---Category: Methods to modify the class definition
 339
 340         SetVisual ( me          : mutable;
 341                     AVisual     : TypeOfStructure from Graphic3d )
 342                 is virtual;
 343         ---Level: Public
 344         ---Purpose: Modifies the visualisation mode for the structure <me>.
 345         ---Warning: It is not possible to display a structure with
 346         --          an incompatible display mode.
 347         --          If the display mode is different from the current one,
 348         --          the structure is erased.
 349         --
 350         --          TOS_WIREFRAME for a wireframe visualisation
 351         --          TOS_SHADING for a shaded visualisation
 352         --          TOS_ALL for all visualisations
 353         --          TOS_COMPUTED for a computed visualisation
 354         --          The default value is TOS_ALL
 355         --
 356         ---Category: Methods to modify the class definition
 357
 358         SetZoomLimit ( me                       : mutable;
 359                        LimitInf, LimitSup       : Real from Standard )
 360         ---Level: Internal
 361         ---Purpose: Modifies the minimum and maximum zoom coefficients
 362         --          for the structure <me>.
 363         --          The default value at the definition of <me> is unlimited.
 364         --  Category: Methods to modify the class definition
 365         --  Warning: Raises StructureDefinitionError if <LimitInf> is
 366         --          greater than <LimitSup> or if <LimitInf> or
 367         --          <LimitSup> is a negative value.
 368         raises StructureDefinitionError from Graphic3d is static;
 369
 370     SetIsForHighlight ( me               : mutable;
 371                         isForHighlight   : Boolean from Standard )
 372         is static;
 373     ---Level: Internal
 374     ---Purpose: marks the structure <me> representing wired structure needed for
 375     --          highlight only so it won't be added to BVH tree.
 376     --  Category: Methods to modify the class definition
 377
 378         UnHighlight ( me        : mutable )
 379                 is static;
 380         ---Level: Public
 381         ---Purpose: Suppresses the highlight for the structure <me>
 382         --           in all the views of the visualiser.
 383         ---Category: Methods to modify the class definition
 384
 385         ----------------------------
 386         -- Category: Compute methods
 387         ----------------------------
 388
 389   Compute (me: mutable)
 390   is virtual;
 391   ---Level: Advanced
 392   ---Category: Methods to modify the class definition
 393
 394         Compute ( me    : mutable;
 395                   aProjector    : DataStructureManager from Graphic3d )
 396                 returns Structure from Graphic3d is virtual;
 397         ---Level: Advanced
 398         ---Purpose: Returns the new Structure defined for the new visualization
 399         ---Category: Methods to modify the class definition
 400
 401         Compute ( me    : mutable;
 402                   aProjector    : DataStructureManager from Graphic3d;
 403                   AMatrix       : Array2OfReal from TColStd )
 404                 returns Structure from Graphic3d is virtual;
 405         ---Level: Advanced
 406         ---Purpose: Returns the new Structure defined for the new visualization
 407         ---Category: Methods to modify the class definition
 408
 409         Compute ( me    : mutable;
 410                   aProjector    : DataStructureManager from Graphic3d;
 411                   aStructure    : in out Structure from Graphic3d )
 412                 is virtual;
 413         ---Level: Advanced
 414         ---Purpose: Returns the new Structure defined for the new visualization
 415         ---Category: Methods to modify the class definition
 416
 417         Compute ( me    : mutable;
 418                   aProjector    : DataStructureManager from Graphic3d;
 419                   AMatrix       : Array2OfReal from TColStd;
 420                   aStructure    : in out Structure from Graphic3d )
 421                 is virtual;
 422         ---Level: Advanced
 423         ---Purpose: Returns the new Structure defined for the new visualization
 424         ---Category: Methods to modify the class definition
 425
 426         ReCompute ( me  : mutable );
 427         ---Level: Advanced
 428         ---Purpose: Forces a new construction of the structure <me>
 429         --          if <me> is displayed and TOS_COMPUTED.
 430         ---Category: Methods to modify the class definition
 431
 432         ReCompute ( me          : mutable;
 433                     aProjector  : DataStructureManager from Graphic3d );
 434         ---Level: Advanced
 435         ---Purpose: Forces a new construction of the structure <me>
 436         --          if <me> is displayed in <aProjetor> and TOS_COMPUTED.
 437         ---Category: Methods to modify the class definition
 438
 439         ----------------------------
 440         -- Category: Inquire methods
 441         ----------------------------
 442
 443         ContainsFacet ( me )
 444                 returns Boolean from Standard
 445                 is static;
 446         ---Level: Public
 447         ---Purpose: Returns Standard_True if the structure <me> contains
 448         --          Polygons, Triangles or Quadrangles.
 449         ---Category: Inquire methods
 450
 451
 452         FillArea3dAspect ( me )
 453                 returns AspectFillArea3d from Graphic3d
 454                 is static;
 455         ---Level: Public
 456         ---Purpose: Returns the values of the current default attributes.
 457         ---Category: Inquire methods
 458
 459         Groups ( me )
 460                 returns SequenceOfGroup from Graphic3d
 461                 is static;
 462         ---C++: return const &
 463         ---Level: Internal
 464         ---Purpose: Returns the groups sequence included in the structure <me> (internal storage).
 465         ---Category: Inquire methods
 466
 467         NumberOfGroups ( me )
 468                 returns Integer from Standard
 469                 is static;
 470         ---Level: Public
 471         ---Purpose: Returns the current number of groups in the
 472         --          structure <me>.
 473         ---Category: Inquire methods
 474
 475   NewGroup ( me : mutable ) returns Group from Graphic3d
 476   is static;
 477   ---Level: Public
 478   ---Purpose: Append new group to this structure.
 479
 480   Remove ( me : mutable;
 481            theGroup : Group from Graphic3d )
 482   is static private;
 483   ---Purpose: Suppress in the structure <me>, the group theGroup.
 484   -- It will be erased at the next screen update.
 485
 486         HighlightColor ( me )
 487                 returns Color from Quantity
 488                 is static;
 489         ---C++: return const&
 490         ---Level: Public
 491         ---Purpose: Returns the highlight color for the Highlight method
 492         --          with the highlight method TOHM_COLOR or TOHM_BOUNDBOX.
 493         ---Category: Inquire methods
 494
 495         IsDeleted ( me )
 496                 returns Boolean from Standard
 497                 is static;
 498         ---Level: Public
 499         ---Purpose: Returns Standard_True if the structure <me> is deleted.
 500         --          <me> is deleted after the call Remove (me).
 501         ---Category: Inquire methods
 502
 503         IsDisplayed ( me )
 504                 returns Boolean from Standard
 505                 is virtual;
 506         ---Level: Public
 507         ---Purpose: Returns the display indicator for the structure <me>.
 508         ---Category: Inquire methods
 509
 510         IsEmpty ( me )
 511                 returns Boolean from Standard
 512                 is static;
 513         ---Level: Public
 514         ---Purpose: Returns Standard_True if the structure <me> is empty.
 515         --  Warning: A structure is empty if :
 516         --              it do not have group or all the groups are empties
 517         --              and it do not have descendant or all the descendants
 518         --              are empties.
 519         ---Category: Inquire methods
 520
 521         IsInfinite ( me )
 522                 returns Boolean from Standard
 523                 is static;
 524         ---Level: Internal
 525         ---Purpose: Returns Standard_True if the structure <me> is infinite.
 526         ---Category: Inquire methods
 527
 528         IsHighlighted ( me )
 529                 returns Boolean from Standard
 530                 is virtual;
 531         ---Level: Public
 532         ---Purpose: Returns the highlight indicator for the structure <me>.
 533         ---Category: Inquire methods
 534
 535         IsSelectable ( me )
 536                 returns Boolean from Standard
 537                 is static;
 538         ---Level: Public
 539         ---Purpose: Returns the detectability indicator for the structure <me>.
 540         ---Category: Inquire methods
 541
 542         IsRotated ( me )
 543                 returns Boolean from Standard
 544                 is static;
 545         ---Level: Public
 546         ---Purpose: Returns Standard_True if the structure <me> is rotated.
 547         --          <=> The transformation != Identity, != Scale, != Translation.
 548         ---Category: Inquire methods
 549
 550         IsTransformed ( me )
 551                 returns Boolean from Standard
 552                 is static;
 553         ---Level: Public
 554         ---Purpose: Returns Standard_True if the structure <me> is transformed.
 555         --          <=> The transformation != Identity.
 556         ---Category: Inquire methods
 557
 558         IsVisible ( me )
 559                 returns Boolean from Standard
 560                 is static;
 561         ---Level: Public
 562         ---Purpose: Returns the visibility indicator for the structure <me>.
 563         ---Category: Inquire methods
 564
 565         Line3dAspect ( me )
 566                 returns AspectLine3d from Graphic3d
 567                 is static;
 568         ---Level: Public
 569         ---Purpose: Returns the values of the current default attributes.
 570         ---Category: Inquire methods
 571
 572         Marker3dAspect ( me )
 573                 returns AspectMarker3d from Graphic3d
 574                 is static;
 575         ---Purpose: Returns the current group of graphic attributes used
 576         -- for 3d marker primitives.
 577
 578     MinMaxValues (me; theToIgnoreInfiniteFlag : Boolean from Standard = Standard_False)
 579     returns Box from Bnd
 580     is static;
 581     ---Level: Public
 582     ---Purpose: Returns the coordinates of the boundary box of the structure <me>.
 583     --          If <theToIgnoreInfiniteFlag> is TRUE, the method returns actual graphical
 584     --          boundaries of the Graphic3d_Group components. Otherwise, the
 585     --          method returns boundaries taking into account infinite state
 586     --          of the structure. This approach generally used for application
 587     --          specific fit operation (e.g. fitting the model into screen,
 588     --          not taking into accout infinite helper elements).
 589     --          Warning: If the structure <me> is empty then the empty box is returned,
 590     --          If the structure <me> is infinite then the whole box is returned.
 591     ---Category: Inquire methods
 592
 593         PrimitivesAspect ( me;
 594                            CTXL : out AspectLine3d from Graphic3d;
 595                            CTXT : out AspectText3d from Graphic3d;
 596                            CTXM : out AspectMarker3d from Graphic3d;
 597                            CTXF : out AspectFillArea3d from Graphic3d )
 598                 is static;
 599         ---Level: Public
 600         ---Purpose: Returns the current values of the default attributes.
 601         ---Category: Inquire methods
 602
 603         Text3dAspect ( me )
 604                 returns AspectText3d from Graphic3d
 605                 is static;
 606         ---Level: Public
 607         ---Purpose: Returns the values of the current default attributes.
 608         ---Category: Inquire methods
 609
 610         Visual ( me )
 611                 returns TypeOfStructure from Graphic3d
 612                 is static;
 613         ---Level: Public
 614         ---Purpose: Returns the visualisation mode for the structure <me>.
 615         ---Category: Inquire methods
 616
 617         ----------------------------------------------------
 618         -- Category: Methods to manage the structure network
 619         ----------------------------------------------------
 620
 621         -----------------------------------------------------
 622         -- Summary of Structure Hierarchies                --
 623         --                                                 --
 624         -- The root  is the top  of a  structure hierarchy --
 625         -- or structure network.                           --
 626         --                                                 --
 627         -- The attributes of a parent structure are passed --
 628         -- passed to its descendants.                      --
 629         --                                                 --
 630         -- The  attributes  of the  descendant  structures --
 631         -- don't affect the parent.                        --
 632         --                                                 --
 633         -- Recursive structure networks are not supported. --
 634         -----------------------------------------------------
 635
 636         AcceptConnection ( myclass;
 637                            AStructure1  : Structure from Graphic3d;
 638                            AStructure2  : Structure from Graphic3d;
 639                            AType        : TypeOfConnection from Graphic3d )
 640                 returns Boolean from Standard;
 641         ---Level: Internal
 642         ---Purpose: Returns Standard_True if the connection is possible between
 643         --          <AStructure1> and <AStructure2> without a creation
 644         --          of a cycle.
 645         --
 646         --          It's not possible to call the method
 647         --             AStructure1->Connect (AStructure2, TypeOfConnection)
 648         --          if
 649         --          - the set of all ancestors of <AStructure1> contains
 650         --            <AStructure1> and if the
 651         --            TypeOfConnection == TOC_DESCENDANT
 652         --          - the set of all descendants of <AStructure1> contains
 653         --            <AStructure2> and if the
 654         --            TypeOfConnection == TOC_ANCESTOR
 655         ---Category: Methods to manage the structure network
 656
 657         Ancestors ( me; SG: in out MapOfStructure from Graphic3d )
 658                 is static;
 659         ---Level: Internal
 660         ---Purpose: Returns the group of structures to which <me> is connected.
 661         ---Category: Methods to manage the structure network
 662
 663         Connect ( me            : mutable;
 664                   AStructure    : Structure from Graphic3d;
 665                   AType         : TypeOfConnection from Graphic3d;
 666                   WithCheck     : Boolean from Standard = Standard_False );
 667         ---Level: Public
 668         ---Purpose: If Atype is TOC_DESCENDANT then add <AStructure>
 669         --          as a child structure of  <me>.
 670         --          If Atype is TOC_ANCESTOR then add <AStructure>
 671         --          as a parent structure of <me>.
 672         --          The connection propagates Display, Highlight, Erase,
 673         --          Remove, and stacks the transformations.
 674         --          No connection if the graph of the structures
 675         --          contains a cycle and <WithCheck> is Standard_True;
 676         ---Category: Methods to manage the structure network
 677
 678         Descendants ( me; SG : in out MapOfStructure from Graphic3d )
 679                 is static;
 680         ---Level: Internal
 681         ---Purpose: Returns the group of structures connected to <me>.
 682         ---Category: Methods to manage the structure network
 683
 684         Disconnect ( me         : mutable;
 685                      AStructure : Structure from Graphic3d )
 686                 is static;
 687         ---Level: Public
 688         ---Purpose: Suppress the connection between <AStructure> and <me>.
 689         ---Category: Methods to manage the structure network
 690
 691         DisconnectAll ( me      : mutable;
 692                         AType   : TypeOfConnection from Graphic3d )
 693                 is static;
 694         ---Level: Public
 695         ---Purpose: If Atype is TOC_DESCENDANT then suppress all
 696         --          the connections with the child structures of <me>.
 697         --          If Atype is TOC_ANCESTOR then suppress all
 698         --          the connections with the parent structures of <me>.
 699         ---Category: Methods to manage the structure network
 700
 701         Network ( myclass;
 702                   AStructure    : Structure from Graphic3d;
 703                   AType         : TypeOfConnection from Graphic3d;
 704                   ASet          : in out MapOfStructure from Graphic3d );
 705         ---Level: Internal
 706         ---Purpose: Returns <ASet> the group of structures :
 707         --          - directly or indirectly connected to <AStructure> if the
 708         --            TypeOfConnection == TOC_DESCENDANT
 709         --          - to which <AStructure> is directly or indirectly connected
 710         --            if the TypeOfConnection == TOC_ANCESTOR
 711         ---Category: Methods to manage the structure network
 712
 713         SetOwner ( me   : mutable;
 714                    Owner        : Address from Standard )
 715                 is static;
 716         ---Level: Advanced
 717
 718         Owner ( me )
 719                 returns Address from Standard
 720                 is static;
 721         ---Level: Advanced
 722
 723         SetHLRValidation ( me   : mutable;
 724                            AFlag        : Boolean from Standard )
 725                 is static;
 726         ---Level: Advanced
 727
 728         HLRValidation ( me )
 729                 returns Boolean from Standard
 730                 is static;
 731         ---Level: Advanced
 732
 733         -----------------------------------------------------------
 734         -- Category: Methods to manage the structure transformation
 735         -----------------------------------------------------------
 736
 737         Composition ( me )
 738                 returns TypeOfComposition from Graphic3d
 739                 is static;
 740         ---Level: Public
 741         ---Purpose: Returns the type of composition applied to matrices
 742         --          of transformation of <me>.
 743         ---Category: Methods to manage the structure transformation
 744
 745         SetTransform ( me       : mutable;
 746                        AMatrix  : Array2OfReal from TColStd;
 747                        AType    : TypeOfComposition from Graphic3d )
 748         ---Level: Public
 749         ---Purpose: Modifies the current local modelling transformation
 750         --          in the structure <me>.
 751         --
 752         --          It is defined as a 4*4 real matrix.
 753         --
 754         --          -------------------
 755         --          | a11 a12 a13  t1 |
 756         --          | a21 a22 a23  t2 |
 757         --          | a31 a32 a33  t3 |
 758         --          |  0   0   0   1  |
 759         --          -------------------
 760         --
 761         --          TypeOfComposition : TOC_REPLACE
 762         --                              TOC_POSTCONCATENATE
 763         --
 764         -- Then the modified Local Modelling Transformation is composed
 765         -- with the current Global Modelling Transformation to create a
 766         -- new Composite Modelling Transformation.
 767         --
 768         -- The compose type specifies the role of the current local
 769         -- modelling transformation (L) in composing the new value for
 770         -- the current local modelling transformation (L'), which is
 771         -- then combined with the current global modelling transforma-
 772         -- tion (G) to calculate the new composite modelling transfor-
 773         -- mation (C).
 774         --
 775         -- TOC_REPLACE
 776         -- The transformation matrix (T) replaces the value of
 777         -- current local modelling transformation (L).
 778         --
 779         --      L' <- T
 780         --      C <- G x L'
 781         --
 782         -- TOC_POSTCONCATENATE
 783         -- The current local modelling transformation (L) is multiplied
 784         -- by the transformation matrix (T):
 785         --
 786         --      L' <- T x L
 787         --      C <- G x L'
 788         --
 789         --  Category: Methods to manage the structure transformation
 790         --  Warning: Raises TransformError if the matrix is not a 4x4 matrix.
 791         raises TransformError from Graphic3d is static;
 792
 793         -- Transform ( me               : mutable;
 794         Transform ( me;
 795                     AMatrix     : in out Array2OfReal from TColStd )
 796                 is static;
 797         ---Level: Public
 798         ---Purpose: Returns the transformation associated with
 799         --          the structure <me>.
 800         ---Category: Methods to manage the structure transformation
 801
 802         SetTransformPersistence( me     : mutable;
 803                                  AFlag  : TransModeFlags from Graphic3d;
 804                                  APoint : Pnt from gp  )
 805         ---Level: Public
 806         ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
 807         is static;
 808
 809         SetTransformPersistence(  me  :  mutable;
 810                                   AFlag  :  TransModeFlags  from  Graphic3d  )
 811         --  Calls previous   method  with  point  (0,0,0)
 812         is  static;
 813
 814
 815         TransformPersistenceMode( me )
 816                         returns TransModeFlags from Graphic3d
 817         ---Level: Public
 818         ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
 819         is static;
 820
 821         TransformPersistencePoint( me )
 822                         returns Pnt from gp
 823         ---Level: Public
 824         ---Purpose: Get the current point of relative modelling transform persistence
 825         is static;
 826
 827   SetMutable ( me           : mutable;
 828                theIsMutable : Boolean from Standard )
 829   is static;
 830   ---Purpose: Sets if the structure location has mutable nature (content or location will be changed regularly).
 831
 832   IsMutable ( me )
 833   returns Boolean from Standard
 834   is static;
 835   ---Purpose: Returns true if structure has mutable nature (content or location are be changed regularly).
 836   -- Mutable structure will be managed in different way than static onces.
 837
 838         ----------------------------
 839         -- Category: Private methods
 840         ----------------------------
 841
 842         ComputeVisual ( me )
 843                 returns TypeOfStructure from Graphic3d
 844                 is static;
 845         ---Level: Internal
 846         ---Category: Private methods
 847
 848         GroupsWithFacet ( me    : mutable;
 849                         ADelta  : Integer from Standard )
 850                 is static private;
 851         ---Level: Internal
 852         ---Purpose: Manages the number of groups in the structure <me>
 853         --          which contains facet.
 854         --          Polygons, Triangles or Quadrangles.
 855         --          <ADelta> = +1 or -1
 856         ---Category: Private methods
 857
 858         GraphicClear ( me       : mutable;
 859                        WithDestruction  : Boolean from Standard )
 860                 is static;
 861         ---Level: Internal
 862         ---Purpose: Clears the structure <me>.
 863         ---Category: Private methods
 864
 865         GraphicConnect ( me     : mutable;
 866                          ADaughter      : Structure from Graphic3d )
 867                 is static;
 868         ---Level: Internal
 869         ---Purpose:
 870         ---Category: Private methods
 871
 872         GraphicDisconnect ( me  : mutable;
 873                             ADaughter   : Structure from Graphic3d )
 874                 is static;
 875         ---Level: Internal
 876         ---Purpose:
 877         ---Category: Private methods
 878
 879         GraphicHighlight ( me           : mutable;
 880                            Method       : TypeOfHighlightMethod from Aspect )
 881                 is static;
 882         ---Level: Internal
 883         ---Purpose: Highlights the structure <me>.
 884         ---Category: Private methods
 885
 886         GraphicTransform ( me           : mutable;
 887                            AMatrix      : Array2OfReal from TColStd )
 888                 is static;
 889         ---Level: Internal
 890         ---Purpose:
 891         ---Category: Private methods
 892
 893         GraphicUnHighlight ( me : mutable )
 894                 is static;
 895         ---Level: Internal
 896         ---Purpose: Suppress the highlight for the structure <me>.
 897         ---Category: Private methods
 898
 899         Identification ( me )
 900                 returns Integer from Standard
 901                 is static;
 902         ---Level: Internal
 903         ---Purpose: Returns the identification number of the structure <me>.
 904         ---Category: Private methods
 905
 906   minMaxCoord (me;
 907                theToIgnoreInfiniteFlag : Boolean from Standard = Standard_False)
 908     returns BndBox4f from Graphic3d
 909   is static private;
 910   ---Purpose: Returns the extreme coordinates found in the structure <me> without transformation applied.
 911
 912   getBox (me;
 913           theBox : out BndBox4d from Graphic3d;
 914           theToIgnoreInfiniteFlag : Boolean from Standard = Standard_False)
 915   is static private;
 916   ---Purpose: Gets untransformed bounding box from structure.
 917
 918   addTransformed (me;
 919                   theBox : out BndBox4d from Graphic3d;
 920                   theToIgnoreInfiniteFlag : Boolean from Standard = Standard_False)
 921   is static private;
 922   ---Purpose: Adds transformed (with myCStructure->Transformation) bounding box of structure to theBox.
 923
 924         PrintNetwork ( myclass;
 925                        AStructure       : Structure from Graphic3d;
 926                        AType            : TypeOfConnection from Graphic3d );
 927         ---Level: Internal
 928         ---Purpose: Prints informations about the network associated
 929         --          with the structure <AStructure>.
 930         ---Category: Private methods
 931
 932         Remove ( me     : mutable;
 933                  APtr   : Address from Standard;
 934                  AType  : TypeOfConnection from Graphic3d )
 935                 is static;
 936         ---Level: Internal
 937         ---Purpose: Suppress the adress <APtr> in the list
 938         --          of descendants or in the list of ancestors.
 939         ---Category: Private methods
 940
 941         SetComputeVisual ( me           : mutable;
 942                            AVisual      : TypeOfStructure from Graphic3d )
 943                 is static;
 944         ---Level: Internal
 945         ---Category: Private methods
 946
 947         StructureManager ( me )
 948                 returns StructureManager from Graphic3d
 949                 is static private;
 950         ---Level: Internal
 951         ---Purpose: Returns the manager to which <me> is associated.
 952         ---Category: Private methods
 953
 954         Transforms ( myclass;
 955                      ATrsf              : Array2OfReal from TColStd;
 956                      X, Y, Z            : Real from Standard;
 957                      NewX, NewY, NewZ   : out Real from Standard );
 958         ---Level: Internal
 959         ---Purpose: Transforms <X>, <Y>, <Z> with the transformation <ATrsf>.
 960         ---Category: Private methods
 961
 962         Transforms ( myclass;
 963                      ATrsf      : Array2OfReal from TColStd;
 964                      Coord      : Vector from Graphic3d )
 965                 returns Vector from Graphic3d;
 966         ---Level: Internal
 967         ---Purpose: Transforms <Coord> with the transformation <ATrsf>.
 968         ---Category: Private methods
 969
 970         Transforms ( myclass;
 971                      ATrsf      : Array2OfReal from TColStd;
 972                      Coord      : Vertex from Graphic3d )
 973                 returns Vertex from Graphic3d;
 974         ---Level: Internal
 975         ---Purpose: Transforms <Coord> with the transformation <ATrsf>.
 976         ---Category: Private methods
 977
 978     TransformBoundaries (myclass;
 979                          theTrsf : Array2OfReal from TColStd;
 980                          theXMin, theYMin, theZMin : in out Real from Standard;
 981                          theXMax, theYMax, theZMax : in out Real from Standard)
 982     is protected;
 983     ---Level: Internal
 984     ---Purpose: Transforms boundaries with <theTrsf> transformation.
 985     ---Category: Private methods
 986
 987         Update ( me )
 988                 is static private;
 989         ---Level: Internal
 990         ---Purpose: Calls the Update method of the StructureManager which
 991         --          contains the Structure <me>.
 992         ---Category: Private methods
 993
 994         UpdateStructure ( me    : mutable;
 995                           CTXL  : AspectLine3d from Graphic3d;
 996                           CTXT  : AspectText3d from Graphic3d;
 997                           CTXM  : AspectMarker3d from Graphic3d;
 998                           CTXF  : AspectFillArea3d from Graphic3d )
 999                 is static private;
1000         ---Level: Internal
1001         ---Purpose: Updates the c structure associated to <me>.
1002         ---Category: Private methods
1003
1004   CStructure (me)
1005   returns CStructure_Handle from Graphic3d
1006   is static;
1007   ---Purpose: Returns the low-level structure
1008   ---C++: return const &
1009   ---C++: inline
1010
1011 fields
1012
1013 --
1014 -- Class        :       Graphic3d_Structure
1015 --
1016 -- Purpose      :       Declaration of variables specific to
1017 --                      graphic structures.
1018 -- Reminder     :       A structure is defined in a manager.
1019 --                      It is a sequence of groups of primitives.
1020 --
1021
1022         -- the associated low-level structure
1023   myCStructure : CStructure_Handle from Graphic3d;
1024
1025         -- the structures to which the structure is attached
1026         myAncestors             :       SequenceOfAddress from TColStd;
1027
1028         -- the structures attached to the structure
1029         myDescendants           :       SequenceOfAddress from TColStd;
1030
1031         -- the highlight method of the structure
1032         myHighlightColor        :       Color from Quantity;
1033         myHighlightMethod       :       TypeOfHighlightMethod from Aspect;
1034
1035         -- the manager accepting the structure
1036         myStructureManager              :       StructureManagerPtr from Graphic3d is protected;
1037         myFirstStructureManager :       StructureManagerPtr from Graphic3d is protected;
1038         myOwner                         :       Address from Standard;
1039
1040         -- the type of visualisation accepted by the structure
1041         myVisual                :       TypeOfStructure from Graphic3d;
1042         myComputeVisual         :       TypeOfStructure from Graphic3d is protected;
1043
1044 friends
1045
1046         -- a lot of methods of Group use the methods of Structure
1047         class Group     from Graphic3d
1048
1049 end Structure;