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