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