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         TypeOfPrimitiveArray        from Graphic3d,
  89         IndexBuffer_Handle          from Graphic3d,
  90         Buffer_Handle               from Graphic3d,
  91         BoundBuffer_Handle          from Graphic3d,
  92         TransModeFlags              from Graphic3d,
  93         CBounds                     from Graphic3d,
  94         Ax2                         from gp
  95
  96     raises
  97
  98         GroupDefinitionError        from Graphic3d,
  99
 100     OutOfRange          from Standard
 101
 102     is
 103         Initialize (theStructure : Structure from Graphic3d)
 104             returns mutable Group from Graphic3d;
 105         ---Level: Public
 106         ---Purpose: Creates a group in the structure <AStructure>.
 107
 108         ---------------------------------------------------
 109         -- Category: Methods to modify the class definition
 110         ---------------------------------------------------
 111
 112         Clear ( me  : mutable;
 113                 theUpdateStructureMgr : Boolean from Standard = Standard_True )
 114         is virtual;
 115         ---Level: Public
 116         ---Purpose: Supress all primitives and attributes of <me>.
 117         --          To clear group without update in Graphic3d_StructureManager
 118         --          pass Standard_False as <theUpdateStructureMgr>. This
 119         --          used on context and viewer destruction, when the pointer
 120         --          to structure manager in Graphic3d_Structure could be
 121         --          already released (pointers are used here to avoid handle
 122         --          cross-reference);
 123         ---Category: Methods to modify the class definition
 124
 125         UpdateAspectLine ( me          : mutable;
 126                            theIsGlobal : Boolean from Standard )
 127         is deferred;
 128
 129         UpdateAspectFace ( me          : mutable;
 130                            theIsGlobal : Boolean from Standard )
 131         is deferred;
 132
 133         UpdateAspectMarker ( me          : mutable;
 134                              theIsGlobal : Boolean from Standard )
 135         is deferred;
 136
 137         UpdateAspectText ( me          : mutable;
 138                            theIsGlobal : Boolean from Standard )
 139         is deferred;
 140
 141         Destroy ( me    : mutable )
 142             is static;
 143         ---Level: Public
 144         ---Purpose: Supress the group <me> in the structure.
 145         ---Category: Methods to modify the class definition
 146         ---C++: alias ~
 147
 148         Remove ( me : mutable )
 149             is static;
 150         ---Level: Public
 151         ---Purpose: Supress the group <me> in the structure.
 152         --  Warning: No more graphic operations in <me> after this call.
 153         ---Category: Methods to modify the class definition
 154
 155         --SetTransformPersistence( me     : mutable;
 156         --                         AFlag  : TransModeFlags from Graphic3d )
 157         ---Level: Public
 158     ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
 159         --is static;
 160
 161     --TransformPersistence( me )
 162     --      returns TransModeFlags from Graphic3d
 163         ---Level: Public
 164     ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
 165         --is static;
 166
 167         SetGroupPrimitivesAspect ( me   : mutable )
 168             is static;
 169         ---Level: Public
 170         ---Purpose: Removes the context for all the line primitives
 171         --      of the group.
 172         ---Category: Methods to modify the class definition
 173
 174         SetGroupPrimitivesAspect ( me   : mutable;
 175                                    CTX  : AspectLine3d from Graphic3d )
 176             is static;
 177         ---Level: Public
 178         ---Purpose: Modifies the context for all the line primitives
 179         --      of the group.
 180         ---Category: Methods to modify the class definition
 181
 182         SetGroupPrimitivesAspect ( me   : mutable;
 183                                    CTX  : AspectFillArea3d from Graphic3d )
 184             is static;
 185         ---Level: Public
 186         ---Purpose: Modifies the context for all the face primitives
 187         --      of the group.
 188         ---Category: Methods to modify the class definition
 189
 190         SetGroupPrimitivesAspect ( me   : mutable;
 191                                    CTX  : AspectText3d from Graphic3d )
 192             is static;
 193         ---Level: Public
 194         ---Purpose: Modifies the context for all the text primitives
 195         --      of the group.
 196         ---Category: Methods to modify the class definition
 197
 198         SetGroupPrimitivesAspect ( me   : mutable;
 199                                    CTX  : AspectMarker3d from Graphic3d )
 200             is static;
 201         ---Level: Public
 202         ---Purpose: Modifies the context for all the marker primitives
 203         --      of the group.
 204         ---Category: Methods to modify the class definition
 205
 206         SetPrimitivesAspect ( me    : mutable;
 207                               CTX   : AspectLine3d from Graphic3d )
 208             is static;
 209         ---Level: Public
 210         ---Purpose: Modifies the current context of the group to give
 211         --      another aspect for all the line primitives created
 212         --      after this call in the group.
 213         ---Category: Methods to modify the class definition
 214
 215         SetPrimitivesAspect ( me    : mutable;
 216                               CTX   : AspectFillArea3d from Graphic3d )
 217             is static;
 218         ---Level: Public
 219         ---Purpose: Modifies the current context of the group to give
 220         --      another aspect for all the face primitives created
 221         --      after this call in the group.
 222         ---Category: Methods to modify the class definition
 223
 224         SetPrimitivesAspect ( me    : mutable;
 225                               CTX   : AspectText3d from Graphic3d )
 226             is static;
 227         ---Level: Public
 228         ---Purpose: Modifies the current context of the group to give
 229         --      another aspect for all the text primitives created
 230         --      after this call in the group.
 231         ---Category: Methods to modify the class definition
 232
 233         SetPrimitivesAspect ( me    : mutable;
 234                               CTX   : AspectMarker3d from Graphic3d )
 235             is static;
 236         ---Level: Public
 237         ---Purpose: Modifies the current context of the group to give
 238         --      another aspect for all the marker primitives created
 239         --      after this call in the group.
 240         ---Category: Methods to modify the class definition
 241
 242         SetMinMaxValues ( me                : mutable;
 243                           XMin, YMin, ZMin  : Real from Standard;
 244                           XMax, YMax, ZMax  : Real from Standard )
 245             is static;
 246         ---Level: Public
 247         ---Purpose: Sets the coordinates of the boundary box of the
 248         --      group <me>.
 249         ---Category: Methods to modify the class definition
 250
 251         -----------------------------------
 252         -- Category: Methods to create Text
 253         -----------------------------------
 254
 255         --------------------------------------------
 256         -- Summary of Texts                       --
 257         --                                        --
 258         -- Text  has  geometric  and nongeometric --
 259         -- attributes.                            --
 260         --                                        --
 261         -- The geometric text attributes are :    --
 262         --                                        --
 263         --  Character Height.                 --
 264         --  Character Up Vector.              --
 265         --  Text Path.                        --
 266         --  Text Alignment Horizontal.        --
 267         --  Text Alignment Vertical.          --
 268         --                                        --
 269         -- The nongeometric text attributes are : --
 270         --                                        --
 271         --  Text Font.                        --
 272         --  Character Spacing.                --
 273         --  Character Expansion Factor.       --
 274         --  Text Color.                       --
 275         --------------------------------------------
 276
 277         Text (  me  : mutable;
 278             AText   : CString from Standard;
 279             APoint  : Vertex from Graphic3d;
 280             AHeight : Real from Standard;
 281             AAngle  : PlaneAngle from Quantity;
 282             ATp : TextPath from Graphic3d;
 283             AHta    : HorizontalTextAlignment from Graphic3d;
 284             AVta    : VerticalTextAlignment from Graphic3d;
 285             EvalMinMax  : Boolean from Standard = Standard_True )
 286         is virtual;
 287         ---Level: Public
 288         ---Purpose: Creates the string <AText> at position <APoint>.
 289         --      The 3D point of attachment is projected. The text is
 290         --      written in the plane of projection.
 291         --      The attributes are given with respect to the plane of
 292         --      projection.
 293         --      AHeight : Height of text.
 294         --            (Relative to the Normalized Projection
 295         --              Coordinates (NPC) Space).
 296         --      AAngle  : Orientation of the text
 297         --            (with respect to the horizontal).
 298         ---Category: Methods to create Text
 299
 300         Text ( me   : mutable;
 301                AText    : CString from Standard;
 302                APoint   : Vertex from Graphic3d;
 303                AHeight  : Real from Standard;
 304                EvalMinMax   : Boolean from Standard = Standard_True )
 305             is static;
 306         ---Level: Public
 307         ---Purpose: Creates the string <AText> at position <APoint>.
 308         --      The 3D point of attachment is projected. The text is
 309         --      written in the plane of projection.
 310         --      The attributes are given with respect to the plane of
 311         --      projection.
 312         --      AHeight : Height of text.
 313         --            (Relative to the Normalized Projection
 314         --              Coordinates (NPC) Space).
 315         --      The other attributes have the following default values:
 316         --      AAngle  : PI / 2.
 317         --      ATp     : TP_RIGHT
 318         --      AHta    : HTA_LEFT
 319         --      AVta    : VTA_BOTTOM
 320         ---Category: Methods to create Text
 321
 322         Text (  me          : mutable;
 323                 AText       : ExtendedString from TCollection;
 324                 APoint      : Vertex from Graphic3d;
 325                 AHeight     : Real from Standard;
 326                 AAngle      : PlaneAngle from Quantity;
 327                 ATp         : TextPath from Graphic3d;
 328                 AHta        : HorizontalTextAlignment from Graphic3d;
 329                 AVta        : VerticalTextAlignment from Graphic3d;
 330                 EvalMinMax  : Boolean from Standard = Standard_True )
 331             is static;
 332         ---Level: Internal
 333         ---Purpose: Creates the string <AText> at position <APoint>.
 334         --      The 3D point of attachment is projected. The text is
 335         --      written in the plane of projection.
 336         --      The attributes are given with respect to the plane of
 337         --      projection.
 338         --      AHeight : Height of text.
 339         --            (Relative to the Normalized Projection
 340         --              Coordinates (NPC) Space).
 341         --      AAngle  : Orientation of the text
 342         --            (with respect to the horizontal).
 343         ---Category: Methods to create Text
 344
 345         Text ( me           : mutable;
 346                AText        : ExtendedString from TCollection;
 347                APoint       : Vertex from Graphic3d;
 348                AHeight      : Real from Standard;
 349                EvalMinMax   : Boolean from Standard = Standard_True )
 350             is static;
 351         ---Level: Internal
 352         ---Purpose: Creates the string <AText> at position <APoint>.
 353         --      The 3D point of attachment is projected. The text is
 354         --      written in the plane of projection.
 355         --      The attributes are given with respect to the plane of
 356         --      projection.
 357         --      AHeight : Height of text.
 358         --            (Relative to the Normalized Projection
 359         --              Coordinates (NPC) Space).
 360         --      The other attributes have the following default values:
 361         --      AAngle  : PI / 2.
 362         --      ATp     : TP_RIGHT
 363         --      AHta    : HTA_LEFT
 364         --      AVta    : VTA_BOTTOM
 365         ---Category: Methods to create Text
 366
 367         ---------------------------------------
 368         ---Category: Methods to create Triangle
 369         ---------------------------------------
 370
 371     AddPrimitiveArray (me              : mutable;
 372                        theType         : TypeOfPrimitiveArray from Graphic3d;
 373                        theIndices      : IndexBuffer_Handle   from Graphic3d;
 374                        theAttribs      : Buffer_Handle        from Graphic3d;
 375                        theBounds       : BoundBuffer_Handle   from Graphic3d;
 376                        theToEvalMinMax : Boolean from Standard = Standard_True) is virtual;
 377     ---Level: Public
 378     ---Purpose: Adds an array of primitives for display
 379
 380     AddPrimitiveArray( me      : mutable;
 381                        thePrim : ArrayOfPrimitives from Graphic3d;
 382                        theToEvalMinMax : Boolean from Standard = Standard_True );
 383     ---Level: Public
 384     ---Purpose: Adds an array of primitives for display
 385
 386     Marker ( me              : mutable;
 387              thePoint        : Vertex from Graphic3d;
 388              theToEvalMinMax : Boolean from Standard = Standard_True )
 389     is static;
 390     ---Level: Public
 391     ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
 392
 393     UserDraw ( me               : mutable;
 394                theObject        : Address from Standard;
 395                theToEvalMinMax  : Boolean from Standard = Standard_True;
 396                theContainsFacet : Boolean from Standard = Standard_False )
 397     is virtual;
 398     ---Level: Public
 399     ---Purpose: Creates a UserDraw primitive using obsolete API.
 400
 401     SetStencilTestOptions (me          : mutable;
 402                            theIsEnabled: Boolean from Standard)
 403     is deferred;
 404     ---Purpose: sets the stencil test to theIsEnabled state;
 405
 406     SetFlippingOptions (me           : mutable;
 407                         theIsEnabled : Boolean from Standard;
 408                         theRefPlane  : Ax2 from gp)
 409     is deferred;
 410     ---Purpose: sets the flipping to theIsEnabled state.
 411
 412         ----------------------------
 413         -- Category: Inquire methods
 414         ----------------------------
 415
 416         IsGroupPrimitivesAspectSet ( me;
 417                     theAspect : GroupAspect from Graphic3d )
 418             returns Boolean from Standard
 419             is static;
 420         ---Level: Public
 421         ---Purpose: Returns TRUE if aspect is set for the group.
 422         ---Category: Inquire methods
 423
 424         GroupPrimitivesAspect ( me;
 425                                 CTXL    : AspectLine3d from Graphic3d;
 426                                 CTXT    : AspectText3d from Graphic3d;
 427                                 CTXM    : AspectMarker3d from Graphic3d;
 428                                 CTXF    : AspectFillArea3d from Graphic3d )
 429                 is static;
 430         ---Level: Public
 431         ---Purpose: Returns the context of all the primitives of the group.
 432         ---Category: Inquire methods
 433
 434         PrimitivesAspect ( me;
 435                            CTXL : AspectLine3d from Graphic3d;
 436                            CTXT : AspectText3d from Graphic3d;
 437                            CTXM : AspectMarker3d from Graphic3d;
 438                            CTXF : AspectFillArea3d from Graphic3d )
 439                 is static;
 440         ---Level: Public
 441         ---Purpose: Returns the last inserted context in the group <me>
 442         --          foreach kind of primitives.
 443         ---Category: Inquire methods
 444
 445         ContainsFacet ( me )
 446             returns Boolean from Standard
 447             is static;
 448         ---Level: Internal
 449         ---Purpose: Returns Standard_True if the group <me> contains
 450         --      Polygons, Triangles or Quadrangles.
 451         ---Category: Inquire methods
 452
 453         IsDeleted ( me )
 454             returns Boolean from Standard
 455             is static;
 456         ---Level: Public
 457         ---Purpose: Returns Standard_True if the group <me> is deleted.
 458         --      <me> is deleted after the call Remove (me) or the
 459         --      associated structure is deleted.
 460         ---Category: Inquire methods
 461
 462         IsEmpty ( me )
 463             returns Boolean from Standard
 464             is static;
 465         ---Level: Public
 466         ---Purpose: Returns Standard_True if the group <me> is empty.
 467         ---Warning: A group is empty if the MinMaxValues method returns :
 468         --      XMin = YMin = ZMin = RealFirst ().
 469         --      XMax = YMax = ZMax = RealLast ().
 470         ---Category: Inquire methods
 471
 472         MinMaxValues ( me;
 473                        XMin, YMin, ZMin : out Real from Standard;
 474                        XMax, YMax, ZMax : out Real from Standard )
 475             is static;
 476         ---Level: Public
 477         ---Purpose: Returns the coordinates of the boundary box of the
 478         --      group <me>.
 479         ---Warning: If the group <me> is empty then :
 480         --      XMin = YMin = ZMin = RealFirst ().
 481         --      XMax = YMax = ZMax = RealLast ().
 482         ---Category: Inquire methods
 483
 484         Structure ( me )
 485             returns mutable Structure from Graphic3d
 486             is static;
 487         ---Level: Public
 488         ---Purpose: Returns the structure containing the group <me>.
 489         ---Category: Inquire methods
 490
 491         ----------------------------
 492         -- Category: Private methods
 493         ----------------------------
 494
 495         MinMaxCoord ( me;
 496                       XMin, YMin, ZMin : out Real from Standard;
 497                       XMax, YMax, ZMax : out Real from Standard )
 498             is static private;
 499         ---Level: Internal
 500         ---Purpose: Returns the extreme coordinates found in the group.
 501         ---Warning: If the group <me> is empty then :
 502         --      XMin = YMin = ZMin = RealFirst ().
 503         --      XMax = YMax = ZMax = RealLast ().
 504         ---Category: Private methods
 505
 506         Update ( me )
 507             is static private;
 508         ---Level: Internal
 509         ---Purpose: Calls the Update method of the StructureManager which
 510         --      contains the associated Structure of the Group <me>.
 511         ---Category: Private methods
 512
 513     fields
 514
 515     --
 516     -- Class    :   Graphic3d_Group
 517     --
 518     -- Purpose  :   Declaration of variables specific to groups
 519     --          of primitives.
 520     --
 521     -- Reminder :   A group is defined in a structure
 522     --          It acts as the smallest editable entity.
 523
 524   -- the state of the different contexts for primitives
 525   myCBitFields   : CBitFields4 from Graphic3d is protected;
 526
 527   -- the structure contains the group
 528   myStructure    : StructurePtr from Graphic3d is protected;
 529
 530   -- the min-max
 531   myBounds       : CBounds from Graphic3d is protected;
 532
 533   ContextLine     : CAspectLine     from Graphic3d is protected;
 534   ContextFillArea : CAspectFillArea from Graphic3d is protected;
 535   ContextMarker   : CAspectMarker   from Graphic3d is protected;
 536   ContextText     : CAspectText     from Graphic3d is protected;
 537
 538 friends
 539
 540   class Structure from Graphic3d
 541
 542 end Group;