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         BndBox4f                    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 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                                    CTX  : AspectLine3d from Graphic3d )
 169             is static;
 170         ---Level: Public
 171         ---Purpose: Modifies the context for all the line primitives
 172         --      of the group.
 173         ---Category: Methods to modify the class definition
 174
 175         SetGroupPrimitivesAspect ( me   : mutable;
 176                                    CTX  : AspectFillArea3d from Graphic3d )
 177             is static;
 178         ---Level: Public
 179         ---Purpose: Modifies the context for all the face primitives
 180         --      of the group.
 181         ---Category: Methods to modify the class definition
 182
 183         SetGroupPrimitivesAspect ( me   : mutable;
 184                                    CTX  : AspectText3d from Graphic3d )
 185             is static;
 186         ---Level: Public
 187         ---Purpose: Modifies the context for all the text primitives
 188         --      of the group.
 189         ---Category: Methods to modify the class definition
 190
 191         SetGroupPrimitivesAspect ( me   : mutable;
 192                                    CTX  : AspectMarker3d from Graphic3d )
 193             is static;
 194         ---Level: Public
 195         ---Purpose: Modifies the context for all the marker primitives
 196         --      of the group.
 197         ---Category: Methods to modify the class definition
 198
 199         SetPrimitivesAspect ( me    : mutable;
 200                               CTX   : AspectLine3d from Graphic3d )
 201             is static;
 202         ---Level: Public
 203         ---Purpose: Modifies the current context of the group to give
 204         --      another aspect for all the line primitives created
 205         --      after this call in the group.
 206         ---Category: Methods to modify the class definition
 207
 208         SetPrimitivesAspect ( me    : mutable;
 209                               CTX   : AspectFillArea3d from Graphic3d )
 210             is static;
 211         ---Level: Public
 212         ---Purpose: Modifies the current context of the group to give
 213         --      another aspect for all the face primitives created
 214         --      after this call in the group.
 215         ---Category: Methods to modify the class definition
 216
 217         SetPrimitivesAspect ( me    : mutable;
 218                               CTX   : AspectText3d from Graphic3d )
 219             is static;
 220         ---Level: Public
 221         ---Purpose: Modifies the current context of the group to give
 222         --      another aspect for all the text primitives created
 223         --      after this call in the group.
 224         ---Category: Methods to modify the class definition
 225
 226         SetPrimitivesAspect ( me    : mutable;
 227                               CTX   : AspectMarker3d from Graphic3d )
 228             is static;
 229         ---Level: Public
 230         ---Purpose: Modifies the current context of the group to give
 231         --      another aspect for all the marker primitives created
 232         --      after this call in the group.
 233         ---Category: Methods to modify the class definition
 234
 235         SetMinMaxValues ( me                : mutable;
 236                           XMin, YMin, ZMin  : Real from Standard;
 237                           XMax, YMax, ZMax  : Real from Standard )
 238             is static;
 239         ---Level: Public
 240         ---Purpose: Sets the coordinates of the boundary box of the
 241         --      group <me>.
 242         ---Category: Methods to modify the class definition
 243
 244         -----------------------------------
 245         -- Category: Methods to create Text
 246         -----------------------------------
 247
 248         --------------------------------------------
 249         -- Summary of Texts                       --
 250         --                                        --
 251         -- Text  has  geometric  and nongeometric --
 252         -- attributes.                            --
 253         --                                        --
 254         -- The geometric text attributes are :    --
 255         --                                        --
 256         --  Character Height.                 --
 257         --  Character Up Vector.              --
 258         --  Text Path.                        --
 259         --  Text Alignment Horizontal.        --
 260         --  Text Alignment Vertical.          --
 261         --                                        --
 262         -- The nongeometric text attributes are : --
 263         --                                        --
 264         --  Text Font.                        --
 265         --  Character Spacing.                --
 266         --  Character Expansion Factor.       --
 267         --  Text Color.                       --
 268         --------------------------------------------
 269
 270         Text (  me  : mutable;
 271             AText   : CString from Standard;
 272             APoint  : Vertex from Graphic3d;
 273             AHeight : Real from Standard;
 274             AAngle  : PlaneAngle from Quantity;
 275             ATp : TextPath from Graphic3d;
 276             AHta    : HorizontalTextAlignment from Graphic3d;
 277             AVta    : VerticalTextAlignment from Graphic3d;
 278             EvalMinMax  : Boolean from Standard = Standard_True )
 279         is virtual;
 280         ---Level: Public
 281         ---Purpose: Creates the string <AText> at position <APoint>.
 282         --      The 3D point of attachment is projected. The text is
 283         --      written in the plane of projection.
 284         --      The attributes are given with respect to the plane of
 285         --      projection.
 286         --      AHeight : Height of text.
 287         --            (Relative to the Normalized Projection
 288         --              Coordinates (NPC) Space).
 289         --      AAngle  : Orientation of the text
 290         --            (with respect to the horizontal).
 291         ---Category: Methods to create Text
 292
 293         Text ( me   : mutable;
 294                AText    : CString from Standard;
 295                APoint   : Vertex from Graphic3d;
 296                AHeight  : Real from Standard;
 297                EvalMinMax   : Boolean from Standard = Standard_True )
 298             is static;
 299         ---Level: Public
 300         ---Purpose: Creates the string <AText> at position <APoint>.
 301         --      The 3D point of attachment is projected. The text is
 302         --      written in the plane of projection.
 303         --      The attributes are given with respect to the plane of
 304         --      projection.
 305         --      AHeight : Height of text.
 306         --            (Relative to the Normalized Projection
 307         --              Coordinates (NPC) Space).
 308         --      The other attributes have the following default values:
 309         --      AAngle  : PI / 2.
 310         --      ATp     : TP_RIGHT
 311         --      AHta    : HTA_LEFT
 312         --      AVta    : VTA_BOTTOM
 313         ---Category: Methods to create Text
 314
 315         Text (  me          : mutable;
 316                 AText       : ExtendedString from TCollection;
 317                 APoint      : Vertex from Graphic3d;
 318                 AHeight     : Real from Standard;
 319                 AAngle      : PlaneAngle from Quantity;
 320                 ATp         : TextPath from Graphic3d;
 321                 AHta        : HorizontalTextAlignment from Graphic3d;
 322                 AVta        : VerticalTextAlignment from Graphic3d;
 323                 EvalMinMax  : Boolean from Standard = Standard_True )
 324             is static;
 325         ---Level: Internal
 326         ---Purpose: Creates the string <AText> at position <APoint>.
 327         --      The 3D point of attachment is projected. The text is
 328         --      written in the plane of projection.
 329         --      The attributes are given with respect to the plane of
 330         --      projection.
 331         --      AHeight : Height of text.
 332         --            (Relative to the Normalized Projection
 333         --              Coordinates (NPC) Space).
 334         --      AAngle  : Orientation of the text
 335         --            (with respect to the horizontal).
 336         ---Category: Methods to create Text
 337
 338         Text ( me           : mutable;
 339                AText        : ExtendedString from TCollection;
 340                APoint       : Vertex from Graphic3d;
 341                AHeight      : Real from Standard;
 342                EvalMinMax   : Boolean from Standard = Standard_True )
 343             is static;
 344         ---Level: Internal
 345         ---Purpose: Creates the string <AText> at position <APoint>.
 346         --      The 3D point of attachment is projected. The text is
 347         --      written in the plane of projection.
 348         --      The attributes are given with respect to the plane of
 349         --      projection.
 350         --      AHeight : Height of text.
 351         --            (Relative to the Normalized Projection
 352         --              Coordinates (NPC) Space).
 353         --      The other attributes have the following default values:
 354         --      AAngle  : PI / 2.
 355         --      ATp     : TP_RIGHT
 356         --      AHta    : HTA_LEFT
 357         --      AVta    : VTA_BOTTOM
 358         ---Category: Methods to create Text
 359
 360         ---------------------------------------
 361         ---Category: Methods to create Triangle
 362         ---------------------------------------
 363
 364     AddPrimitiveArray (me              : mutable;
 365                        theType         : TypeOfPrimitiveArray from Graphic3d;
 366                        theIndices      : IndexBuffer_Handle   from Graphic3d;
 367                        theAttribs      : Buffer_Handle        from Graphic3d;
 368                        theBounds       : BoundBuffer_Handle   from Graphic3d;
 369                        theToEvalMinMax : Boolean from Standard = Standard_True) is virtual;
 370     ---Level: Public
 371     ---Purpose: Adds an array of primitives for display
 372
 373     AddPrimitiveArray( me      : mutable;
 374                        thePrim : ArrayOfPrimitives from Graphic3d;
 375                        theToEvalMinMax : Boolean from Standard = Standard_True );
 376     ---Level: Public
 377     ---Purpose: Adds an array of primitives for display
 378
 379     Marker ( me              : mutable;
 380              thePoint        : Vertex from Graphic3d;
 381              theToEvalMinMax : Boolean from Standard = Standard_True )
 382     is static;
 383     ---Level: Public
 384     ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
 385
 386     UserDraw ( me               : mutable;
 387                theObject        : Address from Standard;
 388                theToEvalMinMax  : Boolean from Standard = Standard_True;
 389                theContainsFacet : Boolean from Standard = Standard_False )
 390     is virtual;
 391     ---Level: Public
 392     ---Purpose: Creates a UserDraw primitive using obsolete API.
 393
 394     SetStencilTestOptions (me          : mutable;
 395                            theIsEnabled: Boolean from Standard)
 396     is deferred;
 397     ---Purpose: sets the stencil test to theIsEnabled state;
 398
 399     SetFlippingOptions (me           : mutable;
 400                         theIsEnabled : Boolean from Standard;
 401                         theRefPlane  : Ax2 from gp)
 402     is deferred;
 403     ---Purpose: sets the flipping to theIsEnabled state.
 404
 405         ----------------------------
 406         -- Category: Inquire methods
 407         ----------------------------
 408
 409         IsGroupPrimitivesAspectSet ( me;
 410                     theAspect : GroupAspect from Graphic3d )
 411             returns Boolean from Standard
 412             is static;
 413         ---Level: Public
 414         ---Purpose: Returns TRUE if aspect is set for the group.
 415         ---Category: Inquire methods
 416
 417         GroupPrimitivesAspect ( me;
 418                                 CTXL    : AspectLine3d from Graphic3d;
 419                                 CTXT    : AspectText3d from Graphic3d;
 420                                 CTXM    : AspectMarker3d from Graphic3d;
 421                                 CTXF    : AspectFillArea3d from Graphic3d )
 422                 is static;
 423         ---Level: Public
 424         ---Purpose: Returns the context of all the primitives of the group.
 425         ---Category: Inquire methods
 426
 427         PrimitivesAspect ( me;
 428                            CTXL : AspectLine3d from Graphic3d;
 429                            CTXT : AspectText3d from Graphic3d;
 430                            CTXM : AspectMarker3d from Graphic3d;
 431                            CTXF : AspectFillArea3d from Graphic3d )
 432                 is static;
 433         ---Level: Public
 434         ---Purpose: Returns the last inserted context in the group <me>
 435         --          foreach kind of primitives.
 436         ---Category: Inquire methods
 437
 438         ContainsFacet ( me )
 439             returns Boolean from Standard
 440             is static;
 441         ---Level: Internal
 442         ---Purpose: Returns Standard_True if the group <me> contains
 443         --      Polygons, Triangles or Quadrangles.
 444         ---Category: Inquire methods
 445
 446         IsDeleted ( me )
 447             returns Boolean from Standard
 448             is static;
 449         ---Level: Public
 450         ---Purpose: Returns Standard_True if the group <me> is deleted.
 451         --      <me> is deleted after the call Remove (me) or the
 452         --      associated structure is deleted.
 453         ---Category: Inquire methods
 454
 455         IsEmpty ( me )
 456             returns Boolean from Standard
 457             is static;
 458         ---Level: Public
 459         ---Purpose: Returns Standard_True if the group <me> is empty.
 460         ---Warning: A group is empty if the MinMaxValues method returns :
 461         --      XMin = YMin = ZMin = RealFirst ().
 462         --      XMax = YMax = ZMax = RealLast ().
 463         ---Category: Inquire methods
 464
 465         MinMaxValues ( me;
 466                        XMin, YMin, ZMin : out Real from Standard;
 467                        XMax, YMax, ZMax : out Real from Standard )
 468             is static;
 469         ---Level: Public
 470         ---Purpose: Returns the coordinates of the boundary box of the
 471         --      group <me>.
 472         ---Warning: If the group <me> is empty then :
 473         --      XMin = YMin = ZMin = RealFirst ().
 474         --      XMax = YMax = ZMax = RealLast ().
 475         ---Category: Inquire methods
 476
 477         BoundingBox ( me )
 478             returns BndBox4f from Graphic3d
 479             is static;
 480         ---Level: Public
 481         ---Purpose: Returns boundary box of the group <me> without transformation applied,
 482         ---if it is specified for the structure.
 483         ---C++: return const &
 484
 485         ChangeBoundingBox ( me : mutable )
 486             returns BndBox4f from Graphic3d
 487             is static;
 488         ---Level: Public
 489         ---Purpose: Returns non-const boundary box of the group <me> without transformation applied,
 490         ---if it is specified for the structure.
 491         ---C++: return &
 492
 493         Structure ( me )
 494             returns Structure from Graphic3d
 495             is static;
 496         ---Level: Public
 497         ---Purpose: Returns the structure containing the group <me>.
 498         ---Category: Inquire methods
 499
 500         ----------------------------
 501         -- Category: Private methods
 502         ----------------------------
 503
 504         MinMaxCoord ( me;
 505                       XMin, YMin, ZMin : out Real from Standard;
 506                       XMax, YMax, ZMax : out Real from Standard )
 507             is static private;
 508         ---Level: Internal
 509         ---Purpose: Returns the extreme coordinates found in the group.
 510         ---Warning: If the group <me> is empty then :
 511         --      XMin = YMin = ZMin = RealFirst ().
 512         --      XMax = YMax = ZMax = RealLast ().
 513         ---Category: Private methods
 514
 515         Update ( me )
 516             is static private;
 517         ---Level: Internal
 518         ---Purpose: Calls the Update method of the StructureManager which
 519         --      contains the associated Structure of the Group <me>.
 520         ---Category: Private methods
 521
 522         SetClosed (me: mutable; theIsClosed : Boolean from Standard);
 523         ---Purpose: Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
 524
 525         IsClosed (me) returns Boolean from Standard;
 526         ---Purpose: Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
 527
 528     fields
 529
 530     --
 531     -- Class    :   Graphic3d_Group
 532     --
 533     -- Purpose  :   Declaration of variables specific to groups
 534     --          of primitives.
 535     --
 536     -- Reminder :   A group is defined in a structure
 537     --          It acts as the smallest editable entity.
 538
 539   -- the state of the different contexts for primitives
 540   myCBitFields   : CBitFields4 from Graphic3d is protected;
 541
 542   -- the structure contains the group
 543   myStructure    : StructurePtr from Graphic3d is protected;
 544
 545   -- the min-max
 546   myBounds        : BndBox4f from Graphic3d is protected;
 547
 548   -- Identifies group forming closed volume. Used to filter groups for back face culling and capping algorithms.
 549   myIsClosed  : Boolean from Standard is protected;
 550
 551   ContextLine     : CAspectLine     from Graphic3d is protected;
 552   ContextFillArea : CAspectFillArea from Graphic3d is protected;
 553   ContextMarker   : CAspectMarker   from Graphic3d is protected;
 554   ContextText     : CAspectText     from Graphic3d is protected;
 555
 556 friends
 557
 558   class Structure from Graphic3d
 559
 560 end Group;