0030153: Visualization, TKOpenGl - AIS_ColoredShape::SynchronizeAspects() doesn't...
[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 <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 <Standard_Transient.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 Standard_Transient
79 {
80   friend class Graphic3d_Structure;
81   DEFINE_STANDARD_RTTIEXT(Graphic3d_Group,Standard_Transient)
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   //! Update presentation aspects after their modification.
150   virtual void SynchronizeAspects() = 0;
151
152   //! Returns TRUE if aspect is set for the group.
153   Standard_EXPORT Standard_Boolean IsGroupPrimitivesAspectSet (const Graphic3d_GroupAspect theAspect) const;
154
155   //! Returns the context of all the primitives of the group.
156   Standard_EXPORT void GroupPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)&     theAspLine,
157                                               const Handle(Graphic3d_AspectText3d)&     theAspText,
158                                               const Handle(Graphic3d_AspectMarker3d)&   theAspMarker,
159                                               const Handle(Graphic3d_AspectFillArea3d)& theAspFill) const;
160
161   //! Returns the last inserted context in the group for each kind of primitives.
162   void PrimitivesAspect (const Handle(Graphic3d_AspectLine3d)&     theAspLine,
163                          const Handle(Graphic3d_AspectText3d)&     theAspText,
164                          const Handle(Graphic3d_AspectMarker3d)&   theAspMarker,
165                          const Handle(Graphic3d_AspectFillArea3d)& theAspFill) const
166   {
167     GroupPrimitivesAspect (theAspLine, theAspText, theAspMarker, theAspFill);
168   }
169
170 public:
171
172   //! Creates the string <AText> at position <APoint>.
173   //! The 3D point of attachment is projected. The text is
174   //! written in the plane of projection.
175   //! The attributes are given with respect to the plane of
176   //! projection.
177   //! AHeight : Height of text.
178   //! (Relative to the Normalized Projection
179   //! Coordinates (NPC) Space).
180   //! AAngle  : Orientation of the text
181   //! (with respect to the horizontal).
182   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);
183
184   //! Creates the string <AText> at position <APoint>.
185   //! The 3D point of attachment is projected. The text is
186   //! written in the plane of projection.
187   //! The attributes are given with respect to the plane of
188   //! projection.
189   //! AHeight : Height of text.
190   //! (Relative to the Normalized Projection
191   //! Coordinates (NPC) Space).
192   //! The other attributes have the following default values:
193   //! AAngle  : PI / 2.
194   //! ATp     : TP_RIGHT
195   //! AHta    : HTA_LEFT
196   //! AVta    : VTA_BOTTOM
197   Standard_EXPORT void Text (const Standard_CString AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Boolean EvalMinMax = Standard_True);
198
199   //! Creates the string <AText> at position <APoint>.
200   //! The 3D point of attachment is projected. The text is
201   //! written in the plane of projection.
202   //! The attributes are given with respect to the plane of
203   //! projection.
204   //! AHeight : Height of text.
205   //! (Relative to the Normalized Projection
206   //! Coordinates (NPC) Space).
207   //! AAngle  : Orientation of the text
208   //! (with respect to the horizontal).
209   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);
210
211   //! Creates the string <AText> at position <APoint>.
212   //! The 3D point of attachment is projected. The text is
213   //! written in the plane of projection.
214   //! The attributes are given with respect to the plane of
215   //! projection.
216   //! AHeight : Height of text.
217   //! (Relative to the Normalized Projection
218   //! Coordinates (NPC) Space).
219   //! The other attributes have the following default values:
220   //! AAngle  : PI / 2.
221   //! ATp     : TP_RIGHT
222   //! AHta    : HTA_LEFT
223   //! AVta    : VTA_BOTTOM
224   Standard_EXPORT void Text (const TCollection_ExtendedString& AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Boolean EvalMinMax = Standard_True);
225
226   //! Creates the string <theText> at orientation <theOrientation> in 3D space.
227   Standard_EXPORT virtual void Text (const Standard_CString                  theTextUtf,
228                                      const gp_Ax2&                           theOrientation,
229                                      const Standard_Real                     theHeight,
230                                      const Standard_Real                     theAngle,
231                                      const Graphic3d_TextPath                theTp,
232                                      const Graphic3d_HorizontalTextAlignment theHTA,
233                                      const Graphic3d_VerticalTextAlignment   theVTA,
234                                      const Standard_Boolean                  theToEvalMinMax = Standard_True,
235                                      const Standard_Boolean                  theHasOwnAnchor = Standard_True);
236
237   //! Creates the string <theText> at orientation <theOrientation> in 3D space.
238   Standard_EXPORT virtual void Text (const TCollection_ExtendedString&       theText,
239                                      const gp_Ax2&                           theOrientation,
240                                      const Standard_Real                     theHeight,
241                                      const Standard_Real                     theAngle,
242                                      const Graphic3d_TextPath                theTp,
243                                      const Graphic3d_HorizontalTextAlignment theHTA,
244                                      const Graphic3d_VerticalTextAlignment   theVTA,
245                                      const Standard_Boolean                  theToEvalMinMax = Standard_True,
246                                      const Standard_Boolean                  theHasOwnAnchor = Standard_True);
247
248
249   //! Adds an array of primitives for display
250   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);
251
252   //! Adds an array of primitives for display
253   Standard_EXPORT void AddPrimitiveArray (const Handle(Graphic3d_ArrayOfPrimitives)& thePrim, const Standard_Boolean theToEvalMinMax = Standard_True);
254
255   //! Creates a primitive array with single marker using AddPrimitiveArray().
256   Standard_EXPORT void Marker (const Graphic3d_Vertex& thePoint, const Standard_Boolean theToEvalMinMax = Standard_True);
257
258 public:
259
260   //! sets the stencil test to theIsEnabled state;
261   Standard_EXPORT virtual void SetStencilTestOptions (const Standard_Boolean theIsEnabled) = 0;
262
263   //! sets the flipping to theIsEnabled state.
264   Standard_EXPORT virtual void SetFlippingOptions (const Standard_Boolean theIsEnabled, const gp_Ax2& theRefPlane) = 0;
265
266   //! Returns true if the group contains Polygons, Triangles or Quadrangles.
267   bool ContainsFacet() const { return myContainsFacet; }
268
269   //! Returns Standard_True if the group <me> is deleted.
270   //! <me> is deleted after the call Remove (me) or the
271   //! associated structure is deleted.
272   Standard_EXPORT Standard_Boolean IsDeleted() const;
273
274   //! Returns Standard_True if the group <me> is empty.
275   Standard_EXPORT Standard_Boolean IsEmpty() const;
276
277   //! Returns the coordinates of the boundary box of the group.
278   Standard_EXPORT void MinMaxValues (Standard_Real& theXMin, Standard_Real& theYMin, Standard_Real& theZMin,
279                                      Standard_Real& theXMax, Standard_Real& theYMax, Standard_Real& theZMax) const;
280
281   //! Sets the coordinates of the boundary box of the group.
282   Standard_EXPORT void SetMinMaxValues (const Standard_Real theXMin, const Standard_Real theYMin, const Standard_Real theZMin,
283                                         const Standard_Real theXMax, const Standard_Real theYMax, const Standard_Real theZMax);
284
285   //! Returns boundary box of the group <me> without transformation applied,
286   const Graphic3d_BndBox4f& BoundingBox() const { return myBounds; }
287
288   //! Returns non-const boundary box of the group <me> without transformation applied,
289   Graphic3d_BndBox4f& ChangeBoundingBox() { return myBounds; }
290
291   //! Returns the structure containing the group <me>.
292   Standard_EXPORT Handle(Graphic3d_Structure) Structure() const;
293
294   //! Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
295   void SetClosed (const bool theIsClosed) { myIsClosed = theIsClosed; }
296
297   //! Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
298   bool IsClosed() const { return myIsClosed; }
299
300 protected:
301
302   //! Creates a group in the structure <AStructure>.
303   Standard_EXPORT Graphic3d_Group(const Handle(Graphic3d_Structure)& theStructure);
304
305   //! Calls the Update method of the StructureManager which
306   //! contains the associated Structure of the Group <me>.
307   Standard_EXPORT void Update() const;
308
309 protected:
310
311   Graphic3d_Structure* myStructure;     //!< pointer to the parent structure
312   Graphic3d_BndBox4f   myBounds;        //!< bounding box
313   bool                 myIsClosed;      //!< flag indicating closed volume
314   bool                 myContainsFacet; //!< flag indicating that this group contains face primitives
315
316 };
317
318 DEFINE_STANDARD_HANDLE(Graphic3d_Group, Standard_Transient)
319
320 #endif // _Graphic3d_Group_HeaderFile