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