src/Graphic3d/Graphic3d_Group.cdl

   1 -- Created on: 1991-09-06
   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 deferred class Group from Graphic3d inherits TShared
  18
  19         ---Version:
  20
  21         ---Purpose: This class allows the definition of groups
  22         --     of primitives inside of graphic objects (presentations).
  23         --     A group contains the primitives and attributes
  24         --     for which the range is limited to this group.
  25         --     The primitives of a group can be globally suppressed.
  26         --
  27         --      There are two main group usage models:
  28         --
  29         --        1) Non-modifiable, or unbounded, group ('black box').
  30         --           Developers can repeat a sequence of
  31         --           SetPrimitivesAspect() with AddPrimitiveArray() methods arbitrary number of times
  32         --           to define arbitrary number of primitive "blocks" each having individual apect values.
  33         --           Any modification of such a group is forbidden, as aspects and primitives are mixed
  34         --           in memory without any high-level logical structure, and any modification is very likely to result
  35         --           in corruption of the group internal data.
  36         --           It is necessary to recreate such a group as a whole when some attribute should be changed.
  37         --           (for example, in terms of AIS it is necessary to re-Compute() the whole presentation each time).
  38         --        2) Bounded group. Developers should specify the necessary group aspects with help of
  39         --           SetGroupPrimitivesAspect() and then add primitives to the group.
  40         --           Such a group have simplified organization in memory (a single block of attributes
  41         --           followed by a block of primitives) and therefore it can be modified, if it is necessary to
  42         --           change parameters of some aspect that has already been set, using methods:
  43         --           IsGroupPrimitivesAspectSet() to detect which aspect was set for primitives;
  44         --           GroupPrimitivesAspect() to read current aspect values
  45         --           and SetGroupPrimitivesAspect() to set new values.
  46         --
  47         --        Developers are strongly recommended to take all the above into account when filling Graphic3d_Group
  48         --        with aspects and primitives and choose the group usage model beforehand out of application needs.
  49
  50         ---Warning:
  51         ---References:
  52
  53     uses
  54
  55         Array1OfInteger             from TColStd,
  56         Array1OfReal                from TColStd,
  57         HArray1OfByte               from TColStd,
  58
  59         ExtendedString              from TCollection,
  60
  61         PlaneAngle                  from Quantity,
  62
  63         Array1OfEdge                from Aspect,
  64         Edge                        from Aspect,
  65
  66         GroupAspect                 from Graphic3d,
  67         AspectLine3d                from Graphic3d,
  68         AspectMarker3d              from Graphic3d,
  69         AspectText3d                from Graphic3d,
  70         AspectFillArea3d            from Graphic3d,
  71         CAspectLine                 from Graphic3d,
  72         CAspectFillArea             from Graphic3d,
  73         CAspectMarker               from Graphic3d,
  74         CAspectText                 from Graphic3d,
  75         CStructurePtr               from Graphic3d,
  76         HorizontalTextAlignment     from Graphic3d,
  77         CBitFields4                 from Graphic3d,
  78         GraphicDriver               from Graphic3d,
  79         Structure                   from Graphic3d,
  80         StructurePtr                from Graphic3d,
  81         TextPath                    from Graphic3d,
  82         Vector                      from Graphic3d,
  83         Array1OfVertex              from Graphic3d,
  84         Array2OfVertex              from Graphic3d,
  85         Vertex                      from Graphic3d,
  86         VerticalTextAlignment       from Graphic3d,
  87         ArrayOfPrimitives           from Graphic3d,
  88         ListOfPArray                from Graphic3d,
  89         TransModeFlags              from Graphic3d,
  90         CBounds                     from Graphic3d,
  91         Ax2                         from gp
  92
  93     raises
  94
  95         GroupDefinitionError        from Graphic3d,
  96
  97     OutOfRange          from Standard
  98
  99     is
 100         Initialize (theStructure : Structure from Graphic3d)
 101             returns mutable Group from Graphic3d;
 102         ---Level: Public
 103         ---Purpose: Creates a group in the structure <AStructure>.
 104
 105         ---------------------------------------------------
 106         -- Category: Methods to modify the class definition
 107         ---------------------------------------------------
 108
 109         Clear ( me  : mutable;
 110                 theUpdateStructureMgr : Boolean from Standard = Standard_True )
 111         is virtual;
 112         ---Level: Public
 113         ---Purpose: Supress all primitives and attributes of <me>.
 114         --          To clear group without update in Graphic3d_StructureManager
 115         --          pass Standard_False as <theUpdateStructureMgr>. This
 116         --          used on context and viewer destruction, when the pointer
 117         --          to structure manager in Graphic3d_Structure could be
 118         --          already released (pointers are used here to avoid handle
 119         --          cross-reference);
 120         ---Category: Methods to modify the class definition
 121
 122         UpdateAspectLine ( me          : mutable;
 123                            theIsGlobal : Boolean from Standard )
 124         is deferred;
 125
 126         UpdateAspectFace ( me          : mutable;
 127                            theIsGlobal : Boolean from Standard )
 128         is deferred;
 129
 130         UpdateAspectMarker ( me          : mutable;
 131                              theIsGlobal : Boolean from Standard )
 132         is deferred;
 133
 134         UpdateAspectText ( me          : mutable;
 135                            theIsGlobal : Boolean from Standard )
 136         is deferred;
 137
 138         Destroy ( me    : mutable )
 139             is static;
 140         ---Level: Public
 141         ---Purpose: Supress the group <me> in the structure.
 142         ---Category: Methods to modify the class definition
 143         ---C++: alias ~
 144
 145         Remove ( me : mutable )
 146             is static;
 147         ---Level: Public
 148         ---Purpose: Supress the group <me> in the structure.
 149         --  Warning: No more graphic operations in <me> after this call.
 150         ---Category: Methods to modify the class definition
 151
 152         --SetTransformPersistence( me     : mutable;
 153         --                         AFlag  : TransModeFlags from Graphic3d )
 154         ---Level: Public
 155     ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
 156         --is static;
 157
 158     --TransformPersistence( me )
 159     --      returns TransModeFlags from Graphic3d
 160         ---Level: Public
 161     ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
 162         --is static;
 163
 164         SetGroupPrimitivesAspect ( me   : mutable )
 165             is static;
 166         ---Level: Public
 167         ---Purpose: Removes the context for all the line primitives
 168         --      of the group.
 169         ---Category: Methods to modify the class definition
 170
 171         SetGroupPrimitivesAspect ( me   : mutable;
 172                                    CTX  : AspectLine3d from Graphic3d )
 173             is static;
 174         ---Level: Public
 175         ---Purpose: Modifies the context for all the line primitives
 176         --      of the group.
 177         ---Category: Methods to modify the class definition
 178
 179         SetGroupPrimitivesAspect ( me   : mutable;
 180                                    CTX  : AspectFillArea3d from Graphic3d )
 181             is static;
 182         ---Level: Public
 183         ---Purpose: Modifies the context for all the face primitives
 184         --      of the group.
 185         ---Category: Methods to modify the class definition
 186
 187         SetGroupPrimitivesAspect ( me   : mutable;
 188                                    CTX  : AspectText3d from Graphic3d )
 189             is static;
 190         ---Level: Public
 191         ---Purpose: Modifies the context for all the text primitives
 192         --      of the group.
 193         ---Category: Methods to modify the class definition
 194
 195         SetGroupPrimitivesAspect ( me   : mutable;
 196                                    CTX  : AspectMarker3d from Graphic3d )
 197             is static;
 198         ---Level: Public
 199         ---Purpose: Modifies the context for all the marker primitives
 200         --      of the group.
 201         ---Category: Methods to modify the class definition
 202
 203         SetPrimitivesAspect ( me    : mutable;
 204                               CTX   : AspectLine3d from Graphic3d )
 205             is static;
 206         ---Level: Public
 207         ---Purpose: Modifies the current context of the group to give
 208         --      another aspect for all the line primitives created
 209         --      after this call in the group.
 210         ---Category: Methods to modify the class definition
 211
 212         SetPrimitivesAspect ( me    : mutable;
 213                               CTX   : AspectFillArea3d from Graphic3d )
 214             is static;
 215         ---Level: Public
 216         ---Purpose: Modifies the current context of the group to give
 217         --      another aspect for all the face primitives created
 218         --      after this call in the group.
 219         ---Category: Methods to modify the class definition
 220
 221         SetPrimitivesAspect ( me    : mutable;
 222                               CTX   : AspectText3d from Graphic3d )
 223             is static;
 224         ---Level: Public
 225         ---Purpose: Modifies the current context of the group to give
 226         --      another aspect for all the text primitives created
 227         --      after this call in the group.
 228         ---Category: Methods to modify the class definition
 229
 230         SetPrimitivesAspect ( me    : mutable;
 231                               CTX   : AspectMarker3d from Graphic3d )
 232             is static;
 233         ---Level: Public
 234         ---Purpose: Modifies the current context of the group to give
 235         --      another aspect for all the marker primitives created
 236         --      after this call in the group.
 237         ---Category: Methods to modify the class definition
 238
 239         SetMinMaxValues ( me                : mutable;
 240                           XMin, YMin, ZMin  : Real from Standard;
 241                           XMax, YMax, ZMax  : Real from Standard )
 242             is static;
 243         ---Level: Public
 244         ---Purpose: Sets the coordinates of the boundary box of the
 245         --      group <me>.
 246         ---Category: Methods to modify the class definition
 247
 248         -----------------------------------
 249         -- Category: Methods to create Text
 250         -----------------------------------
 251
 252         --------------------------------------------
 253         -- Summary of Texts                       --
 254         --                                        --
 255         -- Text  has  geometric  and nongeometric --
 256         -- attributes.                            --
 257         --                                        --
 258         -- The geometric text attributes are :    --
 259         --                                        --
 260         --  Character Height.                 --
 261         --  Character Up Vector.              --
 262         --  Text Path.                        --
 263         --  Text Alignment Horizontal.        --
 264         --  Text Alignment Vertical.          --
 265         --                                        --
 266         -- The nongeometric text attributes are : --
 267         --                                        --
 268         --  Text Font.                        --
 269         --  Character Spacing.                --
 270         --  Character Expansion Factor.       --
 271         --  Text Color.                       --
 272         --------------------------------------------
 273
 274         Text (  me  : mutable;
 275             AText   : CString from Standard;
 276             APoint  : Vertex from Graphic3d;
 277             AHeight : Real from Standard;
 278             AAngle  : PlaneAngle from Quantity;
 279             ATp : TextPath from Graphic3d;
 280             AHta    : HorizontalTextAlignment from Graphic3d;
 281             AVta    : VerticalTextAlignment from Graphic3d;
 282             EvalMinMax  : Boolean from Standard = Standard_True )
 283         is virtual;
 284         ---Level: Public
 285         ---Purpose: Creates the string <AText> at position <APoint>.
 286         --      The 3D point of attachment is projected. The text is
 287         --      written in the plane of projection.
 288         --      The attributes are given with respect to the plane of
 289         --      projection.
 290         --      AHeight : Height of text.
 291         --            (Relative to the Normalized Projection
 292         --              Coordinates (NPC) Space).
 293         --      AAngle  : Orientation of the text
 294         --            (with respect to the horizontal).
 295         ---Category: Methods to create Text
 296
 297         Text ( me   : mutable;
 298                AText    : CString from Standard;
 299                APoint   : Vertex from Graphic3d;
 300                AHeight  : Real from Standard;
 301                EvalMinMax   : Boolean from Standard = Standard_True )
 302             is static;
 303         ---Level: Public
 304         ---Purpose: Creates the string <AText> at position <APoint>.
 305         --      The 3D point of attachment is projected. The text is
 306         --      written in the plane of projection.
 307         --      The attributes are given with respect to the plane of
 308         --      projection.
 309         --      AHeight : Height of text.
 310         --            (Relative to the Normalized Projection
 311         --              Coordinates (NPC) Space).
 312         --      The other attributes have the following default values:
 313         --      AAngle  : PI / 2.
 314         --      ATp     : TP_RIGHT
 315         --      AHta    : HTA_LEFT
 316         --      AVta    : VTA_BOTTOM
 317         ---Category: Methods to create Text
 318
 319         Text (  me          : mutable;
 320                 AText       : ExtendedString from TCollection;
 321                 APoint      : Vertex from Graphic3d;
 322                 AHeight     : Real from Standard;
 323                 AAngle      : PlaneAngle from Quantity;
 324                 ATp         : TextPath from Graphic3d;
 325                 AHta        : HorizontalTextAlignment from Graphic3d;
 326                 AVta        : VerticalTextAlignment from Graphic3d;
 327                 EvalMinMax  : Boolean from Standard = Standard_True )
 328             is static;
 329         ---Level: Internal
 330         ---Purpose: Creates the string <AText> at position <APoint>.
 331         --      The 3D point of attachment is projected. The text is
 332         --      written in the plane of projection.
 333         --      The attributes are given with respect to the plane of
 334         --      projection.
 335         --      AHeight : Height of text.
 336         --            (Relative to the Normalized Projection
 337         --              Coordinates (NPC) Space).
 338         --      AAngle  : Orientation of the text
 339         --            (with respect to the horizontal).
 340         ---Category: Methods to create Text
 341
 342         Text ( me           : mutable;
 343                AText        : ExtendedString from TCollection;
 344                APoint       : Vertex from Graphic3d;
 345                AHeight      : Real from Standard;
 346                EvalMinMax   : Boolean from Standard = Standard_True )
 347             is static;
 348         ---Level: Internal
 349         ---Purpose: Creates the string <AText> at position <APoint>.
 350         --      The 3D point of attachment is projected. The text is
 351         --      written in the plane of projection.
 352         --      The attributes are given with respect to the plane of
 353         --      projection.
 354         --      AHeight : Height of text.
 355         --            (Relative to the Normalized Projection
 356         --              Coordinates (NPC) Space).
 357         --      The other attributes have the following default values:
 358         --      AAngle  : PI / 2.
 359         --      ATp     : TP_RIGHT
 360         --      AHta    : HTA_LEFT
 361         --      AVta    : VTA_BOTTOM
 362         ---Category: Methods to create Text
 363
 364         ---------------------------------------
 365         ---Category: Methods to create Triangle
 366         ---------------------------------------
 367
 368     AddPrimitiveArray( me      : mutable;
 369                        thePrim : ArrayOfPrimitives from Graphic3d;
 370                        theToEvalMinMax : Boolean from Standard = Standard_True ) is virtual;
 371     ---Level: Public
 372     ---Purpose: Adds an array of primitives for display
 373
 374     Marker ( me              : mutable;
 375              thePoint        : Vertex from Graphic3d;
 376              theToEvalMinMax : Boolean from Standard = Standard_True )
 377     is static;
 378     ---Level: Public
 379     ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
 380
 381     UserDraw ( me               : mutable;
 382                theObject        : Address from Standard;
 383                theToEvalMinMax  : Boolean from Standard = Standard_True;
 384                theContainsFacet : Boolean from Standard = Standard_False )
 385     is virtual;
 386     ---Level: Public
 387     ---Purpose: Creates a UserDraw primitive using obsolete API.
 388
 389     SetStencilTestOptions (me          : mutable;
 390                            theIsEnabled: Boolean from Standard)
 391     is deferred;
 392     ---Purpose: sets the stencil test to theIsEnabled state;
 393
 394     SetFlippingOptions (me           : mutable;
 395                         theIsEnabled : Boolean from Standard;
 396                         theRefPlane  : Ax2 from gp)
 397     is deferred;
 398     ---Purpose: sets the flipping to theIsEnabled state.
 399
 400         ----------------------------
 401         -- Category: Inquire methods
 402         ----------------------------
 403
 404         IsGroupPrimitivesAspectSet ( me;
 405                     theAspect : GroupAspect from Graphic3d )
 406             returns Boolean from Standard
 407             is static;
 408         ---Level: Public
 409         ---Purpose: Returns TRUE if aspect is set for the group.
 410         ---Category: Inquire methods
 411
 412         GroupPrimitivesAspect ( me;
 413                                 CTXL    : AspectLine3d from Graphic3d;
 414                                 CTXT    : AspectText3d from Graphic3d;
 415                                 CTXM    : AspectMarker3d from Graphic3d;
 416                                 CTXF    : AspectFillArea3d from Graphic3d )
 417                 is static;
 418         ---Level: Public
 419         ---Purpose: Returns the context of all the primitives of the group.
 420         ---Category: Inquire methods
 421
 422         PrimitivesAspect ( me;
 423                            CTXL : AspectLine3d from Graphic3d;
 424                            CTXT : AspectText3d from Graphic3d;
 425                            CTXM : AspectMarker3d from Graphic3d;
 426                            CTXF : AspectFillArea3d from Graphic3d )
 427                 is static;
 428         ---Level: Public
 429         ---Purpose: Returns the last inserted context in the group <me>
 430         --          foreach kind of primitives.
 431         ---Category: Inquire methods
 432
 433         ContainsFacet ( me )
 434             returns Boolean from Standard
 435             is static;
 436         ---Level: Internal
 437         ---Purpose: Returns Standard_True if the group <me> contains
 438         --      Polygons, Triangles or Quadrangles.
 439         ---Category: Inquire methods
 440
 441         IsDeleted ( me )
 442             returns Boolean from Standard
 443             is static;
 444         ---Level: Public
 445         ---Purpose: Returns Standard_True if the group <me> is deleted.
 446         --      <me> is deleted after the call Remove (me) or the
 447         --      associated structure is deleted.
 448         ---Category: Inquire methods
 449
 450         IsEmpty ( me )
 451             returns Boolean from Standard
 452             is static;
 453         ---Level: Public
 454         ---Purpose: Returns Standard_True if the group <me> is empty.
 455         ---Warning: A group is empty if the MinMaxValues method returns :
 456         --      XMin = YMin = ZMin = RealFirst ().
 457         --      XMax = YMax = ZMax = RealLast ().
 458         ---Category: Inquire methods
 459
 460         MinMaxValues ( me;
 461                        XMin, YMin, ZMin : out Real from Standard;
 462                        XMax, YMax, ZMax : out Real from Standard )
 463             is static;
 464         ---Level: Public
 465         ---Purpose: Returns the coordinates of the boundary box of the
 466         --      group <me>.
 467         ---Warning: If the group <me> is empty then :
 468         --      XMin = YMin = ZMin = RealFirst ().
 469         --      XMax = YMax = ZMax = RealLast ().
 470         ---Category: Inquire methods
 471
 472         Structure ( me )
 473             returns mutable Structure from Graphic3d
 474             is static;
 475         ---Level: Public
 476         ---Purpose: Returns the structure containing the group <me>.
 477         ---Category: Inquire methods
 478
 479         ----------------------------
 480         -- Category: Private methods
 481         ----------------------------
 482
 483         MinMaxCoord ( me;
 484                       XMin, YMin, ZMin : out Real from Standard;
 485                       XMax, YMax, ZMax : out Real from Standard )
 486             is static private;
 487         ---Level: Internal
 488         ---Purpose: Returns the extreme coordinates found in the group.
 489         ---Warning: If the group <me> is empty then :
 490         --      XMin = YMin = ZMin = RealFirst ().
 491         --      XMax = YMax = ZMax = RealLast ().
 492         ---Category: Private methods
 493
 494         Update ( me )
 495             is static private;
 496         ---Level: Internal
 497         ---Purpose: Calls the Update method of the StructureManager which
 498         --      contains the associated Structure of the Group <me>.
 499         ---Category: Private methods
 500
 501     fields
 502
 503     --
 504     -- Class    :   Graphic3d_Group
 505     --
 506     -- Purpose  :   Declaration of variables specific to groups
 507     --          of primitives.
 508     --
 509     -- Reminder :   A group is defined in a structure
 510     --          It acts as the smallest editable entity.
 511
 512   -- the state of the different contexts for primitives
 513   myCBitFields   : CBitFields4 from Graphic3d is protected;
 514
 515   -- the structure contains the group
 516   myStructure    : StructurePtr from Graphic3d is protected;
 517
 518   -- the min-max
 519   myBounds       : CBounds from Graphic3d is protected;
 520
 521   ContextLine     : CAspectLine     from Graphic3d is protected;
 522   ContextFillArea : CAspectFillArea from Graphic3d is protected;
 523   ContextMarker   : CAspectMarker   from Graphic3d is protected;
 524   ContextText     : CAspectText     from Graphic3d is protected;
 525
 526   -- temporary field - to be removed
 527   myListOfPArray : ListOfPArray from Graphic3d is protected;
 528
 529 friends
 530
 531   class Structure from Graphic3d
 532
 533 end Group;