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-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21 --      27/09/97 ; PCT : add manual control of  textures
  22 --              11/97 ; CAL : ajout polyline par 2 points
  23 --      16/06/2000 : ATS: Study G005 - Group store presentations of it's objects in field
  24 --                        MyListOfPArray to avoid deletion of handle-manipulating
  25 --                        primitives.
  26 class Group from Graphic3d inherits TShared
  27
  28         ---Version:
  29
  30         ---Purpose: This class allows the definition of groups
  31         --     of primitives inside of graphic objects (presentations).
  32         --     A group contains the primitives and attributes
  33         --     for which the range is limited to this group.
  34         --     The primitives of a group can be globally suppressed.
  35         --
  36         --      There are two main group usage models:
  37         --
  38         --        1) Non-modifiable, or unbounded, group ('black box').
  39         --           Developers can repeat a sequence of
  40         --           SetPrimitivesAspect() with AddPrimitiveArray() methods arbitrary number of times
  41         --           to define arbitrary number of primitive "blocks" each having individual apect values.
  42         --           Any modification of such a group is forbidden, as aspects and primitives are mixed
  43         --           in memory without any high-level logical structure, and any modification is very likely to result
  44         --           in corruption of the group internal data.
  45         --           It is necessary to recreate such a group as a whole when some attribute should be changed.
  46         --           (for example, in terms of AIS it is necessary to re-Compute() the whole presentation each time).
  47         --        2) Bounded group. Developers should specify the necessary group aspects with help of
  48         --           SetGroupPrimitivesAspect() and then add primitives to the group.
  49         --           Such a group have simplified organization in memory (a single block of attributes
  50         --           followed by a block of primitives) and therefore it can be modified, if it is necessary to
  51         --           change parameters of some aspect that has already been set, using methods:
  52         --           IsGroupPrimitivesAspectSet() to detect which aspect was set for primitives;
  53         --           GroupPrimitivesAspect() to read current aspect values
  54         --           and SetGroupPrimitivesAspect() to set new values.
  55         --
  56         --        Developers are strongly recommended to take all the above into account when filling Graphic3d_Group
  57         --        with aspects and primitives and choose the group usage model beforehand out of application needs.
  58
  59         ---Warning:
  60         ---References:
  61
  62     uses
  63
  64         Array1OfInteger             from TColStd,
  65         Array1OfReal                from TColStd,
  66         HArray1OfByte               from TColStd,
  67
  68         ExtendedString              from TCollection,
  69
  70         PlaneAngle                  from Quantity,
  71
  72         Array1OfEdge                from Aspect,
  73         Edge                        from Aspect,
  74
  75         GroupAspect                 from Graphic3d,
  76         AspectLine3d                from Graphic3d,
  77         AspectMarker3d              from Graphic3d,
  78         AspectText3d                from Graphic3d,
  79         AspectFillArea3d            from Graphic3d,
  80         HorizontalTextAlignment     from Graphic3d,
  81         CBitFields4                 from Graphic3d,
  82         CGroup                      from Graphic3d,
  83         GraphicDriver               from Graphic3d,
  84         Structure                   from Graphic3d,
  85         TextPath                    from Graphic3d,
  86         Vector                      from Graphic3d,
  87         Array1OfVertex              from Graphic3d,
  88         Array2OfVertex              from Graphic3d,
  89         Vertex                      from Graphic3d,
  90         VerticalTextAlignment       from Graphic3d,
  91         ArrayOfPrimitives           from Graphic3d,
  92         ListOfPArray                from Graphic3d,
  93         TransModeFlags              from Graphic3d,
  94         CBounds                     from Graphic3d
  95
  96     raises
  97
  98         GroupDefinitionError        from Graphic3d,
  99         PickIdDefinitionError       from Graphic3d,
 100     OutOfRange          from Standard
 101
 102     is
 103         Create ( AStructure : 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 static;
 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         Destroy ( me    : mutable )
 126             is static;
 127         ---Level: Public
 128         ---Purpose: Supress the group <me> in the structure.
 129         ---Category: Methods to modify the class definition
 130         ---C++: alias ~
 131
 132         Remove ( me : mutable )
 133             is static;
 134         ---Level: Public
 135         ---Purpose: Supress the group <me> in the structure.
 136         --  Warning: No more graphic operations in <me> after this call.
 137         ---Category: Methods to modify the class definition
 138
 139         --SetTransformPersistence( me     : mutable;
 140         --                         AFlag  : TransModeFlags from Graphic3d )
 141         ---Level: Public
 142     ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
 143         --is static;
 144
 145     --TransformPersistence( me )
 146     --      returns TransModeFlags from Graphic3d
 147         ---Level: Public
 148     ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
 149         --is static;
 150
 151         SetGroupPrimitivesAspect ( me   : mutable )
 152             is static;
 153         ---Level: Public
 154         ---Purpose: Removes the context for all the line primitives
 155         --      of the group.
 156         ---Category: Methods to modify the class definition
 157
 158         SetGroupPrimitivesAspect ( me   : mutable;
 159                                    CTX  : AspectLine3d from Graphic3d )
 160             is static;
 161         ---Level: Public
 162         ---Purpose: Modifies the context for all the line primitives
 163         --      of the group.
 164         ---Category: Methods to modify the class definition
 165
 166         SetGroupPrimitivesAspect ( me   : mutable;
 167                                    CTX  : AspectFillArea3d from Graphic3d )
 168             is static;
 169         ---Level: Public
 170         ---Purpose: Modifies the context for all the face primitives
 171         --      of the group.
 172         ---Category: Methods to modify the class definition
 173
 174         SetGroupPrimitivesAspect ( me   : mutable;
 175                                    CTX  : AspectText3d from Graphic3d )
 176             is static;
 177         ---Level: Public
 178         ---Purpose: Modifies the context for all the text primitives
 179         --      of the group.
 180         ---Category: Methods to modify the class definition
 181
 182         SetGroupPrimitivesAspect ( me   : mutable;
 183                                    CTX  : AspectMarker3d from Graphic3d )
 184             is static;
 185         ---Level: Public
 186         ---Purpose: Modifies the context for all the marker primitives
 187         --      of the group.
 188         ---Category: Methods to modify the class definition
 189
 190         SetPrimitivesAspect ( me    : mutable;
 191                               CTX   : AspectLine3d from Graphic3d )
 192             is static;
 193         ---Level: Public
 194         ---Purpose: Modifies the current context of the group to give
 195         --      another aspect for all the line primitives created
 196         --      after this call in the group.
 197         ---Category: Methods to modify the class definition
 198
 199         SetPrimitivesAspect ( me    : mutable;
 200                               CTX   : AspectFillArea3d 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 face primitives created
 205         --      after this call in the group.
 206         ---Category: Methods to modify the class definition
 207
 208         SetPrimitivesAspect ( me    : mutable;
 209                               CTX   : AspectText3d 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 text primitives created
 214         --      after this call in the group.
 215         ---Category: Methods to modify the class definition
 216
 217         SetPrimitivesAspect ( me    : mutable;
 218                               CTX   : AspectMarker3d 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 marker primitives created
 223         --      after this call in the group.
 224         ---Category: Methods to modify the class definition
 225
 226         SetMinMaxValues ( me                : mutable;
 227                           XMin, YMin, ZMin  : Real from Standard;
 228                           XMax, YMax, ZMax  : Real from Standard )
 229             is static;
 230         ---Level: Public
 231         ---Purpose: Sets the coordinates of the boundary box of the
 232         --      group <me>.
 233         ---Category: Methods to modify the class definition
 234
 235         -----------------------------------
 236         -- Category: Methods to create Text
 237         -----------------------------------
 238
 239         --------------------------------------------
 240         -- Summary of Texts                       --
 241         --                                        --
 242         -- Text  has  geometric  and nongeometric --
 243         -- attributes.                            --
 244         --                                        --
 245         -- The geometric text attributes are :    --
 246         --                                        --
 247         --  Character Height.                 --
 248         --  Character Up Vector.              --
 249         --  Text Path.                        --
 250         --  Text Alignment Horizontal.        --
 251         --  Text Alignment Vertical.          --
 252         --                                        --
 253         -- The nongeometric text attributes are : --
 254         --                                        --
 255         --  Text Font.                        --
 256         --  Character Spacing.                --
 257         --  Character Expansion Factor.       --
 258         --  Text Color.                       --
 259         --------------------------------------------
 260
 261         Text (  me  : mutable;
 262             AText   : CString from Standard;
 263             APoint  : Vertex from Graphic3d;
 264             AHeight : Real from Standard;
 265             AAngle  : PlaneAngle from Quantity;
 266             ATp : TextPath from Graphic3d;
 267             AHta    : HorizontalTextAlignment from Graphic3d;
 268             AVta    : VerticalTextAlignment from Graphic3d;
 269             EvalMinMax  : Boolean from Standard = Standard_True )
 270             is static;
 271         ---Level: Public
 272         ---Purpose: Creates the string <AText> at position <APoint>.
 273         --      The 3D point of attachment is projected. The text is
 274         --      written in the plane of projection.
 275         --      The attributes are given with respect to the plane of
 276         --      projection.
 277         --      AHeight : Height of text.
 278         --            (Relative to the Normalized Projection
 279         --              Coordinates (NPC) Space).
 280         --      AAngle  : Orientation of the text
 281         --            (with respect to the horizontal).
 282         ---Category: Methods to create Text
 283
 284         Text ( me   : mutable;
 285                AText    : CString from Standard;
 286                APoint   : Vertex from Graphic3d;
 287                AHeight  : Real from Standard;
 288                EvalMinMax   : Boolean from Standard = Standard_True )
 289             is static;
 290         ---Level: Public
 291         ---Purpose: Creates the string <AText> at position <APoint>.
 292         --      The 3D point of attachment is projected. The text is
 293         --      written in the plane of projection.
 294         --      The attributes are given with respect to the plane of
 295         --      projection.
 296         --      AHeight : Height of text.
 297         --            (Relative to the Normalized Projection
 298         --              Coordinates (NPC) Space).
 299         --      The other attributes have the following default values:
 300         --      AAngle  : PI / 2.
 301         --      ATp     : TP_RIGHT
 302         --      AHta    : HTA_LEFT
 303         --      AVta    : VTA_BOTTOM
 304         ---Category: Methods to create Text
 305
 306         Text (  me          : mutable;
 307                 AText       : ExtendedString from TCollection;
 308                 APoint      : Vertex from Graphic3d;
 309                 AHeight     : Real from Standard;
 310                 AAngle      : PlaneAngle from Quantity;
 311                 ATp         : TextPath from Graphic3d;
 312                 AHta        : HorizontalTextAlignment from Graphic3d;
 313                 AVta        : VerticalTextAlignment from Graphic3d;
 314                 EvalMinMax  : Boolean from Standard = Standard_True )
 315             is static;
 316         ---Level: Internal
 317         ---Purpose: Creates the string <AText> at position <APoint>.
 318         --      The 3D point of attachment is projected. The text is
 319         --      written in the plane of projection.
 320         --      The attributes are given with respect to the plane of
 321         --      projection.
 322         --      AHeight : Height of text.
 323         --            (Relative to the Normalized Projection
 324         --              Coordinates (NPC) Space).
 325         --      AAngle  : Orientation of the text
 326         --            (with respect to the horizontal).
 327         ---Category: Methods to create Text
 328
 329         Text ( me           : mutable;
 330                AText        : ExtendedString from TCollection;
 331                APoint       : Vertex from Graphic3d;
 332                AHeight      : Real from Standard;
 333                EvalMinMax   : Boolean from Standard = Standard_True )
 334             is static;
 335         ---Level: Internal
 336         ---Purpose: Creates the string <AText> at position <APoint>.
 337         --      The 3D point of attachment is projected. The text is
 338         --      written in the plane of projection.
 339         --      The attributes are given with respect to the plane of
 340         --      projection.
 341         --      AHeight : Height of text.
 342         --            (Relative to the Normalized Projection
 343         --              Coordinates (NPC) Space).
 344         --      The other attributes have the following default values:
 345         --      AAngle  : PI / 2.
 346         --      ATp     : TP_RIGHT
 347         --      AHta    : HTA_LEFT
 348         --      AVta    : VTA_BOTTOM
 349         ---Category: Methods to create Text
 350
 351         ---------------------------------------
 352         ---Category: Methods to create Triangle
 353         ---------------------------------------
 354
 355     AddPrimitiveArray( me      : mutable;
 356                        elem    : ArrayOfPrimitives from Graphic3d;
 357           EvalMinMax: Boolean from Standard = Standard_True );
 358         ---Level: Public
 359     ---Purpose: Adds an array of primitives for display
 360
 361     UserDraw ( me           : mutable;
 362                AnObject     : Address from Standard;
 363                EvalMinMax   : Boolean from Standard = Standard_True;
 364                ContainsFacet: Boolean from Standard = Standard_False
 365     )
 366     ---Level: Public
 367     ---Purpose: Creates an UserDraw primitive
 368     --  Category: Methods to create UserDraw
 369     --  Warning: Raises GroupDefinitionError if ...
 370     raises GroupDefinitionError from Graphic3d is static;
 371
 372     SetStencilTestOptions (me          : mutable;
 373                            theIsEnabled: Boolean from Standard);
 374     ---Purpose: sets the stencil test to theIsEnabled state;
 375
 376         ----------------------------
 377         -- Category: Inquire methods
 378         ----------------------------
 379
 380         IsGroupPrimitivesAspectSet ( me;
 381                     theAspect : GroupAspect from Graphic3d )
 382             returns Boolean from Standard
 383             is static;
 384         ---Level: Public
 385         ---Purpose: Returns TRUE if aspect is set for the group.
 386         ---Category: Inquire methods
 387
 388         GroupPrimitivesAspect ( me;
 389                                 CTXL    : AspectLine3d from Graphic3d;
 390                                 CTXT    : AspectText3d from Graphic3d;
 391                                 CTXM    : AspectMarker3d from Graphic3d;
 392                                 CTXF    : AspectFillArea3d from Graphic3d )
 393                 is static;
 394         ---Level: Public
 395         ---Purpose: Returns the context of all the primitives of the group.
 396         ---Category: Inquire methods
 397
 398         PrimitivesAspect ( me;
 399                            CTXL : AspectLine3d from Graphic3d;
 400                            CTXT : AspectText3d from Graphic3d;
 401                            CTXM : AspectMarker3d from Graphic3d;
 402                            CTXF : AspectFillArea3d from Graphic3d )
 403                 is static;
 404         ---Level: Public
 405         ---Purpose: Returns the last inserted context in the group <me>
 406         --          foreach kind of primitives.
 407         ---Category: Inquire methods
 408
 409         ContainsFacet ( me )
 410             returns Boolean from Standard
 411             is static;
 412         ---Level: Internal
 413         ---Purpose: Returns Standard_True if the group <me> contains
 414         --      Polygons, Triangles or Quadrangles.
 415         ---Category: Inquire methods
 416
 417         IsDeleted ( me )
 418             returns Boolean from Standard
 419             is static;
 420         ---Level: Public
 421         ---Purpose: Returns Standard_True if the group <me> is deleted.
 422         --      <me> is deleted after the call Remove (me) or the
 423         --      associated structure is deleted.
 424         ---Category: Inquire methods
 425
 426         IsEmpty ( me )
 427             returns Boolean from Standard
 428             is static;
 429         ---Level: Public
 430         ---Purpose: Returns Standard_True if the group <me> is empty.
 431         ---Warning: A group is empty if the MinMaxValues method returns :
 432         --      XMin = YMin = ZMin = RealFirst ().
 433         --      XMax = YMax = ZMax = RealLast ().
 434         ---Category: Inquire methods
 435
 436         MinMaxValues ( me;
 437                        XMin, YMin, ZMin : out Real from Standard;
 438                        XMax, YMax, ZMax : out Real from Standard )
 439             is static;
 440         ---Level: Public
 441         ---Purpose: Returns the coordinates of the boundary box of the
 442         --      group <me>.
 443         ---Warning: If the group <me> is empty then :
 444         --      XMin = YMin = ZMin = RealFirst ().
 445         --      XMax = YMax = ZMax = RealLast ().
 446         ---Category: Inquire methods
 447
 448         Structure ( me )
 449             returns mutable Structure from Graphic3d
 450             is static;
 451         ---Level: Public
 452         ---Purpose: Returns the structure containing the group <me>.
 453         ---Category: Inquire methods
 454
 455         ----------------------------
 456         -- Category: Private methods
 457         ----------------------------
 458
 459         MinMaxCoord ( me;
 460                       XMin, YMin, ZMin : out Real from Standard;
 461                       XMax, YMax, ZMax : out Real from Standard )
 462             is static private;
 463         ---Level: Internal
 464         ---Purpose: Returns the extreme coordinates found in the group.
 465         ---Warning: If the group <me> is empty then :
 466         --      XMin = YMin = ZMin = RealFirst ().
 467         --      XMax = YMax = ZMax = RealLast ().
 468         ---Category: Private methods
 469
 470         Update ( me )
 471             is static private;
 472         ---Level: Internal
 473         ---Purpose: Calls the Update method of the StructureManager which
 474         --      contains the associated Structure of the Group <me>.
 475         ---Category: Private methods
 476
 477     fields
 478
 479     --
 480     -- Class    :   Graphic3d_Group
 481     --
 482     -- Purpose  :   Declaration of variables specific to groups
 483     --          of primitives.
 484     --
 485     -- Reminder :   A group is defined in a structure
 486     --          It acts as the smallest editable entity.
 487
 488         -- the associated C structure
 489         MyCGroup        :   CGroup from Graphic3d;
 490
 491         -- the graphic driver used
 492         MyGraphicDriver     :   GraphicDriver from Graphic3d;
 493
 494         -- the state of the different contexts for primitives
 495         MyCBitFields        :   CBitFields4 from Graphic3d;
 496
 497         -- the structure contains the group
 498         MyPtrStructure      :   Address from Standard;
 499
 500         -- the min-max
 501     MyBounds                :       CBounds from Graphic3d;
 502
 503     MyListOfPArray          :   ListOfPArray from Graphic3d;
 504
 505     MyMarkArray             :       HArray1OfByte from TColStd;
 506     MyMarkWidth             :       Integer from Standard;
 507     MyMarkHeight            :       Integer from Standard;
 508
 509     friends
 510
 511         Remove from class Structure from Graphic3d
 512             ( me : mutable; AGroup : Group from Graphic3d )
 513
 514     end Group;