src/Graphic3d/Graphic3d_Group.hxx

   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 #ifndef _Graphic3d_Group_HeaderFile
  18 #define _Graphic3d_Group_HeaderFile
  19
  20 #include <Standard.hxx>
  21 #include <Standard_Type.hxx>
  22
  23 #include <Graphic3d_BndBox4f.hxx>
  24 #include <Standard_Boolean.hxx>
  25 #include <Graphic3d_AspectLine3d.hxx>
  26 #include <Graphic3d_AspectFillArea3d.hxx>
  27 #include <Graphic3d_AspectText3d.hxx>
  28 #include <Graphic3d_AspectMarker3d.hxx>
  29 #include <MMgt_TShared.hxx>
  30 #include <Standard_Real.hxx>
  31 #include <Standard_CString.hxx>
  32 #include <Graphic3d_Vertex.hxx>
  33 #include <Graphic3d_TextPath.hxx>
  34 #include <Graphic3d_HorizontalTextAlignment.hxx>
  35 #include <Graphic3d_VerticalTextAlignment.hxx>
  36 #include <Graphic3d_TypeOfPrimitiveArray.hxx>
  37 #include <Graphic3d_IndexBuffer.hxx>
  38 #include <Graphic3d_Buffer.hxx>
  39 #include <Graphic3d_BoundBuffer.hxx>
  40 #include <Standard_Address.hxx>
  41 #include <Graphic3d_GroupAspect.hxx>
  42 #include <gp_Ax2.hxx>
  43 #include <TCollection_ExtendedString.hxx>
  44
  45 class Graphic3d_Structure;
  46 class Graphic3d_ArrayOfPrimitives;
  47
  48 //! This class allows the definition of groups
  49 //! of primitives inside of graphic objects (presentations).
  50 //! A group contains the primitives and attributes
  51 //! for which the range is limited to this group.
  52 //! The primitives of a group can be globally suppressed.
  53 //!
  54 //! There are two main group usage models:
  55 //!
  56 //! 1) Non-modifiable, or unbounded, group ('black box').
  57 //! Developers can repeat a sequence of
  58 //! SetPrimitivesAspect() with AddPrimitiveArray() methods arbitrary number of times
  59 //! to define arbitrary number of primitive "blocks" each having individual apect values.
  60 //! Any modification of such a group is forbidden, as aspects and primitives are mixed
  61 //! in memory without any high-level logical structure, and any modification is very likely to result
  62 //! in corruption of the group internal data.
  63 //! It is necessary to recreate such a group as a whole when some attribute should be changed.
  64 //! (for example, in terms of AIS it is necessary to re-Compute() the whole presentation each time).
  65 //! 2) Bounded group. Developers should specify the necessary group aspects with help of
  66 //! SetGroupPrimitivesAspect() and then add primitives to the group.
  67 //! Such a group have simplified organization in memory (a single block of attributes
  68 //! followed by a block of primitives) and therefore it can be modified, if it is necessary to
  69 //! change parameters of some aspect that has already been set, using methods:
  70 //! IsGroupPrimitivesAspectSet() to detect which aspect was set for primitives;
  71 //! GroupPrimitivesAspect() to read current aspect values
  72 //! and SetGroupPrimitivesAspect() to set new values.
  73 //!
  74 //! Developers are strongly recommended to take all the above into account when filling Graphic3d_Group
  75 //! with aspects and primitives and choose the group usage model beforehand out of application needs.
  76 //! Note that some Graphic3d_Group class virtual methods contain only base implementation
  77 //! that is extended by the descendant class in OpenGl package.
  78 class Graphic3d_Group : public MMgt_TShared
  79 {
  80   friend class Graphic3d_Structure;
  81   DEFINE_STANDARD_RTTIEXT(Graphic3d_Group,MMgt_TShared)
  82
  83 public:
  84
  85   //! Supress all primitives and attributes of <me>.
  86   //! To clear group without update in Graphic3d_StructureManager
  87   //! pass Standard_False as <theUpdateStructureMgr>. This
  88   //! used on context and viewer destruction, when the pointer
  89   //! to structure manager in Graphic3d_Structure could be
  90   //! already released (pointers are used here to avoid handle
  91   //! cross-reference);
  92   Standard_EXPORT virtual void Clear (const Standard_Boolean theUpdateStructureMgr = Standard_True);
  93
  94   //! Supress the group <me> in the structure.
  95   Standard_EXPORT virtual ~Graphic3d_Group();
  96
  97   //! Supress the group <me> in the structure.
  98   //! Warning: No more graphic operations in <me> after this call.
  99   //! Modifies the current modelling transform persistence (pan, zoom or rotate)
 100   //! Get the current modelling transform persistence (pan, zoom or rotate)
 101   Standard_EXPORT void Remove();
 102
 103 public:
 104
 105   //! Return line aspect.
 106   virtual Handle(Graphic3d_AspectLine3d) LineAspect() const = 0;
 107
 108   //! Assign line aspect to the group.
 109   virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)& theAspect) = 0;
 110
 111   //! Return fill area aspect.
 112   virtual Handle(Graphic3d_AspectFillArea3d) FillAreaAspect() const = 0;
 113
 114   //! Modifies the context for all the face primitives of the group.
 115   virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect) = 0;
 116
 117   //! Return text aspect.
 118   virtual Handle(Graphic3d_AspectText3d) TextAspect() const = 0;
 119
 120   //! Modifies the context for all the text primitives of the group.
 121   virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectText3d)& theAspect) = 0;
 122
 123   //! Return marker aspect.
 124   virtual Handle(Graphic3d_AspectMarker3d) MarkerAspect() const = 0;
 125
 126   //! Modifies the context for all the marker primitives of the group.
 127   virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectMarker3d)& theAspect) = 0;
 128
 129   //! Modifies the current context of the group to give
 130   //! another aspect for all the line primitives created
 131   //! after this call in the group.
 132   virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)& theAspect) = 0;
 133
 134   //! Modifies the current context of the group to give
 135   //! another aspect for all the face primitives created
 136   //! after this call in the group.
 137   virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect) = 0;
 138
 139   //! Modifies the current context of the group to give
 140   //! another aspect for all the text primitives created
 141   //! after this call in the group.
 142   virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectText3d)& theAspect) = 0;
 143
 144   //! Modifies the current context of the group to give
 145   //! another aspect for all the marker primitives created
 146   //! after this call in the group.
 147   virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectMarker3d)& theAspect) = 0;
 148
 149   //! Returns TRUE if aspect is set for the group.
 150   Standard_EXPORT Standard_Boolean IsGroupPrimitivesAspectSet (const Graphic3d_GroupAspect theAspect) const;
 151
 152   //! Returns the context of all the primitives of the group.
 153   Standard_EXPORT void GroupPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)&     theAspLine,
 154                                               const Handle(Graphic3d_AspectText3d)&     theAspText,
 155                                               const Handle(Graphic3d_AspectMarker3d)&   theAspMarker,
 156                                               const Handle(Graphic3d_AspectFillArea3d)& theAspFill) const;
 157
 158   //! Returns the last inserted context in the group for each kind of primitives.
 159   void PrimitivesAspect (const Handle(Graphic3d_AspectLine3d)&     theAspLine,
 160                          const Handle(Graphic3d_AspectText3d)&     theAspText,
 161                          const Handle(Graphic3d_AspectMarker3d)&   theAspMarker,
 162                          const Handle(Graphic3d_AspectFillArea3d)& theAspFill) const
 163   {
 164     GroupPrimitivesAspect (theAspLine, theAspText, theAspMarker, theAspFill);
 165   }
 166
 167 public:
 168
 169   //! Creates the string <AText> at position <APoint>.
 170   //! The 3D point of attachment is projected. The text is
 171   //! written in the plane of projection.
 172   //! The attributes are given with respect to the plane of
 173   //! projection.
 174   //! AHeight : Height of text.
 175   //! (Relative to the Normalized Projection
 176   //! Coordinates (NPC) Space).
 177   //! AAngle  : Orientation of the text
 178   //! (with respect to the horizontal).
 179   Standard_EXPORT virtual void Text (const Standard_CString AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Real AAngle, const Graphic3d_TextPath ATp, const Graphic3d_HorizontalTextAlignment AHta, const Graphic3d_VerticalTextAlignment AVta, const Standard_Boolean EvalMinMax = Standard_True);
 180
 181   //! Creates the string <AText> at position <APoint>.
 182   //! The 3D point of attachment is projected. The text is
 183   //! written in the plane of projection.
 184   //! The attributes are given with respect to the plane of
 185   //! projection.
 186   //! AHeight : Height of text.
 187   //! (Relative to the Normalized Projection
 188   //! Coordinates (NPC) Space).
 189   //! The other attributes have the following default values:
 190   //! AAngle  : PI / 2.
 191   //! ATp     : TP_RIGHT
 192   //! AHta    : HTA_LEFT
 193   //! AVta    : VTA_BOTTOM
 194   Standard_EXPORT void Text (const Standard_CString AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Boolean EvalMinMax = Standard_True);
 195
 196   //! Creates the string <AText> at position <APoint>.
 197   //! The 3D point of attachment is projected. The text is
 198   //! written in the plane of projection.
 199   //! The attributes are given with respect to the plane of
 200   //! projection.
 201   //! AHeight : Height of text.
 202   //! (Relative to the Normalized Projection
 203   //! Coordinates (NPC) Space).
 204   //! AAngle  : Orientation of the text
 205   //! (with respect to the horizontal).
 206   Standard_EXPORT void Text (const TCollection_ExtendedString& AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Real AAngle, const Graphic3d_TextPath ATp, const Graphic3d_HorizontalTextAlignment AHta, const Graphic3d_VerticalTextAlignment AVta, const Standard_Boolean EvalMinMax = Standard_True);
 207
 208   //! Creates the string <AText> at position <APoint>.
 209   //! The 3D point of attachment is projected. The text is
 210   //! written in the plane of projection.
 211   //! The attributes are given with respect to the plane of
 212   //! projection.
 213   //! AHeight : Height of text.
 214   //! (Relative to the Normalized Projection
 215   //! Coordinates (NPC) Space).
 216   //! The other attributes have the following default values:
 217   //! AAngle  : PI / 2.
 218   //! ATp     : TP_RIGHT
 219   //! AHta    : HTA_LEFT
 220   //! AVta    : VTA_BOTTOM
 221   Standard_EXPORT void Text (const TCollection_ExtendedString& AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Boolean EvalMinMax = Standard_True);
 222
 223   //! Creates the string <theText> at orientation <theOrientation> in 3D space.
 224   Standard_EXPORT virtual void Text (const Standard_CString                  theTextUtf,
 225                                      const gp_Ax2&                           theOrientation,
 226                                      const Standard_Real                     theHeight,
 227                                      const Standard_Real                     theAngle,
 228                                      const Graphic3d_TextPath                theTp,
 229                                      const Graphic3d_HorizontalTextAlignment theHTA,
 230                                      const Graphic3d_VerticalTextAlignment   theVTA,
 231                                      const Standard_Boolean                  theToEvalMinMax = Standard_True,
 232                                      const Standard_Boolean                  theHasOwnAnchor = Standard_True);
 233
 234   //! Creates the string <theText> at orientation <theOrientation> in 3D space.
 235   Standard_EXPORT virtual void Text (const TCollection_ExtendedString&       theText,
 236                                      const gp_Ax2&                           theOrientation,
 237                                      const Standard_Real                     theHeight,
 238                                      const Standard_Real                     theAngle,
 239                                      const Graphic3d_TextPath                theTp,
 240                                      const Graphic3d_HorizontalTextAlignment theHTA,
 241                                      const Graphic3d_VerticalTextAlignment   theVTA,
 242                                      const Standard_Boolean                  theToEvalMinMax = Standard_True,
 243                                      const Standard_Boolean                  theHasOwnAnchor = Standard_True);
 244
 245
 246   //! Adds an array of primitives for display
 247   Standard_EXPORT virtual void AddPrimitiveArray (const Graphic3d_TypeOfPrimitiveArray theType, const Handle(Graphic3d_IndexBuffer)& theIndices, const Handle(Graphic3d_Buffer)& theAttribs, const Handle(Graphic3d_BoundBuffer)& theBounds, const Standard_Boolean theToEvalMinMax = Standard_True);
 248
 249   //! Adds an array of primitives for display
 250   Standard_EXPORT void AddPrimitiveArray (const Handle(Graphic3d_ArrayOfPrimitives)& thePrim, const Standard_Boolean theToEvalMinMax = Standard_True);
 251
 252   //! Creates a primitive array with single marker using AddPrimitiveArray().
 253   Standard_EXPORT void Marker (const Graphic3d_Vertex& thePoint, const Standard_Boolean theToEvalMinMax = Standard_True);
 254
 255 public:
 256
 257   //! sets the stencil test to theIsEnabled state;
 258   Standard_EXPORT virtual void SetStencilTestOptions (const Standard_Boolean theIsEnabled) = 0;
 259
 260   //! sets the flipping to theIsEnabled state.
 261   Standard_EXPORT virtual void SetFlippingOptions (const Standard_Boolean theIsEnabled, const gp_Ax2& theRefPlane) = 0;
 262
 263   //! Returns true if the group contains Polygons, Triangles or Quadrangles.
 264   bool ContainsFacet() const { return myContainsFacet; }
 265
 266   //! Returns Standard_True if the group <me> is deleted.
 267   //! <me> is deleted after the call Remove (me) or the
 268   //! associated structure is deleted.
 269   Standard_EXPORT Standard_Boolean IsDeleted() const;
 270
 271   //! Returns Standard_True if the group <me> is empty.
 272   Standard_EXPORT Standard_Boolean IsEmpty() const;
 273
 274   //! Returns the coordinates of the boundary box of the group.
 275   Standard_EXPORT void MinMaxValues (Standard_Real& theXMin, Standard_Real& theYMin, Standard_Real& theZMin,
 276                                      Standard_Real& theXMax, Standard_Real& theYMax, Standard_Real& theZMax) const;
 277
 278   //! Sets the coordinates of the boundary box of the group.
 279   Standard_EXPORT void SetMinMaxValues (const Standard_Real theXMin, const Standard_Real theYMin, const Standard_Real theZMin,
 280                                         const Standard_Real theXMax, const Standard_Real theYMax, const Standard_Real theZMax);
 281
 282   //! Returns boundary box of the group <me> without transformation applied,
 283   const Graphic3d_BndBox4f& BoundingBox() const { return myBounds; }
 284
 285   //! Returns non-const boundary box of the group <me> without transformation applied,
 286   Graphic3d_BndBox4f& ChangeBoundingBox() { return myBounds; }
 287
 288   //! Returns the structure containing the group <me>.
 289   Standard_EXPORT Handle(Graphic3d_Structure) Structure() const;
 290
 291   //! Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
 292   void SetClosed (const bool theIsClosed) { myIsClosed = theIsClosed; }
 293
 294   //! Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
 295   bool IsClosed() const { return myIsClosed; }
 296
 297 protected:
 298
 299   //! Creates a group in the structure <AStructure>.
 300   Standard_EXPORT Graphic3d_Group(const Handle(Graphic3d_Structure)& theStructure);
 301
 302   //! Calls the Update method of the StructureManager which
 303   //! contains the associated Structure of the Group <me>.
 304   Standard_EXPORT void Update() const;
 305
 306 protected:
 307
 308   Graphic3d_Structure* myStructure;     //!< pointer to the parent structure
 309   Graphic3d_BndBox4f   myBounds;        //!< bounding box
 310   bool                 myIsClosed;      //!< flag indicating closed volume
 311   bool                 myContainsFacet; //!< flag indicating that this group contains face primitives
 312
 313 };
 314
 315 DEFINE_STANDARD_HANDLE(Graphic3d_Group, MMgt_TShared)
 316
 317 #endif // _Graphic3d_Group_HeaderFile