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
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _Graphic3d_Group_HeaderFile
18 #define _Graphic3d_Group_HeaderFile
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>
36 #include <TCollection_ExtendedString.hxx>
38 class Graphic3d_Structure;
39 class Graphic3d_ArrayOfPrimitives;
41 class Graphic3d_TransformPers;
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.
49 //! There are two main group usage models:
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.
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
75 friend class Graphic3d_Structure;
76 DEFINE_STANDARD_RTTIEXT(Graphic3d_Group,Standard_Transient)
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
87 Standard_EXPORT virtual void Clear (const Standard_Boolean theUpdateStructureMgr = Standard_True);
89 //! Suppress the group <me> in the structure.
90 Standard_EXPORT virtual ~Graphic3d_Group();
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();
100 //! Return fill area aspect.
101 virtual Handle(Graphic3d_Aspects) Aspects() const = 0;
103 //! Modifies the context for all the face primitives of the group.
104 virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_Aspects)& theAspect) = 0;
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;
109 //! Update presentation aspects after their modification.
110 virtual void SynchronizeAspects() = 0;
112 //! Replace aspects specified in the replacement map.
113 virtual void ReplaceAspects (const Graphic3d_MapOfAspectsToAspects& theMap) = 0;
115 //! Adds a text for display
116 Standard_EXPORT virtual void AddText (const Handle(Graphic3d_Text)& theTextParams,
117 const Standard_Boolean theToEvalMinMax = Standard_True);
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);
126 //! Adds an array of primitives for display
127 Standard_EXPORT void AddPrimitiveArray (const Handle(Graphic3d_ArrayOfPrimitives)& thePrim, const Standard_Boolean theToEvalMinMax = Standard_True);
131 //! sets the stencil test to theIsEnabled state;
132 Standard_EXPORT virtual void SetStencilTestOptions (const Standard_Boolean theIsEnabled) = 0;
134 //! sets the flipping to theIsEnabled state.
135 Standard_EXPORT virtual void SetFlippingOptions (const Standard_Boolean theIsEnabled, const gp_Ax2& theRefPlane) = 0;
137 //! Return transformation persistence.
138 const Handle(Graphic3d_TransformPers)& TransformPersistence() const { return myTrsfPers; }
140 //! Set transformation persistence.
141 Standard_EXPORT virtual void SetTransformPersistence (const Handle(Graphic3d_TransformPers)& theTrsfPers);
143 //! Returns Standard_True if the group <me> is deleted.
144 //! <me> is deleted after the call Remove (me) or the
145 //! associated structure is deleted.
146 Standard_EXPORT Standard_Boolean IsDeleted() const;
148 //! Returns Standard_True if the group <me> is empty.
149 Standard_EXPORT Standard_Boolean IsEmpty() const;
151 //! Returns the coordinates of the boundary box of the group.
152 Standard_EXPORT void MinMaxValues (Standard_Real& theXMin, Standard_Real& theYMin, Standard_Real& theZMin,
153 Standard_Real& theXMax, Standard_Real& theYMax, Standard_Real& theZMax) const;
155 //! Sets the coordinates of the boundary box of the group.
156 Standard_EXPORT void SetMinMaxValues (const Standard_Real theXMin, const Standard_Real theYMin, const Standard_Real theZMin,
157 const Standard_Real theXMax, const Standard_Real theYMax, const Standard_Real theZMax);
159 //! Returns boundary box of the group <me> without transformation applied,
160 const Graphic3d_BndBox4f& BoundingBox() const { return myBounds; }
162 //! Returns non-const boundary box of the group <me> without transformation applied,
163 Graphic3d_BndBox4f& ChangeBoundingBox() { return myBounds; }
165 //! Returns the structure containing the group <me>.
166 Standard_EXPORT Handle(Graphic3d_Structure) Structure() const;
168 //! Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
169 void SetClosed (const bool theIsClosed) { myIsClosed = theIsClosed; }
171 //! Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
172 bool IsClosed() const { return myIsClosed; }
174 //! @name obsolete methods
177 Standard_DEPRECATED("Deprecated method Marker(), pass Graphic3d_ArrayOfPoints to AddPrimitiveArray() instead")
178 Standard_EXPORT void Marker (const Graphic3d_Vertex& thePoint, const Standard_Boolean theToEvalMinMax = Standard_True);
180 //! Creates the string <AText> at position <APoint>.
181 //! The 3D point of attachment is projected. The text is
182 //! written in the plane of projection.
183 //! The attributes are given with respect to the plane of
185 //! AHeight : Height of text.
186 //! (Relative to the Normalized Projection
187 //! Coordinates (NPC) Space).
188 //! AAngle : Orientation of the text
189 //! (with respect to the horizontal).
190 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
191 Standard_EXPORT virtual void Text (const Standard_CString AText,
192 const Graphic3d_Vertex& APoint,
193 const Standard_Real AHeight,
194 const Standard_Real AAngle,
195 const Graphic3d_TextPath ATp,
196 const Graphic3d_HorizontalTextAlignment AHta,
197 const Graphic3d_VerticalTextAlignment AVta,
198 const Standard_Boolean EvalMinMax = Standard_True);
200 //! Creates the string <AText> at position <APoint>.
201 //! The 3D point of attachment is projected. The text is
202 //! written in the plane of projection.
203 //! The attributes are given with respect to the plane of
205 //! AHeight : Height of text.
206 //! (Relative to the Normalized Projection
207 //! Coordinates (NPC) Space).
208 //! The other attributes have the following default values:
212 //! AVta : VTA_BOTTOM
213 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
214 Standard_EXPORT void Text (const Standard_CString AText,
215 const Graphic3d_Vertex& APoint,
216 const Standard_Real AHeight,
217 const Standard_Boolean EvalMinMax = Standard_True);
219 //! Creates the string <AText> at position <APoint>.
220 //! The 3D point of attachment is projected. The text is
221 //! written in the plane of projection.
222 //! The attributes are given with respect to the plane of
224 //! AHeight : Height of text.
225 //! (Relative to the Normalized Projection
226 //! Coordinates (NPC) Space).
227 //! AAngle : Orientation of the text
228 //! (with respect to the horizontal).
229 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
230 Standard_EXPORT void Text (const TCollection_ExtendedString& AText,
231 const Graphic3d_Vertex& APoint,
232 const Standard_Real AHeight,
233 const Standard_Real AAngle,
234 const Graphic3d_TextPath ATp,
235 const Graphic3d_HorizontalTextAlignment AHta,
236 const Graphic3d_VerticalTextAlignment AVta,
237 const Standard_Boolean EvalMinMax = Standard_True);
239 //! Creates the string <AText> at position <APoint>.
240 //! The 3D point of attachment is projected. The text is
241 //! written in the plane of projection.
242 //! The attributes are given with respect to the plane of
244 //! AHeight : Height of text.
245 //! (Relative to the Normalized Projection
246 //! Coordinates (NPC) Space).
247 //! The other attributes have the following default values:
251 //! AVta : VTA_BOTTOM
252 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
253 Standard_EXPORT void Text (const TCollection_ExtendedString& AText,
254 const Graphic3d_Vertex& APoint,
255 const Standard_Real AHeight,
256 const Standard_Boolean EvalMinMax = Standard_True);
258 //! Creates the string <theText> at orientation <theOrientation> in 3D space.
259 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
260 Standard_EXPORT virtual void Text (const Standard_CString theTextUtf,
261 const gp_Ax2& theOrientation,
262 const Standard_Real theHeight,
263 const Standard_Real theAngle,
264 const Graphic3d_TextPath theTp,
265 const Graphic3d_HorizontalTextAlignment theHTA,
266 const Graphic3d_VerticalTextAlignment theVTA,
267 const Standard_Boolean theToEvalMinMax = Standard_True,
268 const Standard_Boolean theHasOwnAnchor = Standard_True);
270 //! Creates the string <theText> at orientation <theOrientation> in 3D space.
271 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
272 Standard_EXPORT virtual void Text (const TCollection_ExtendedString& theText,
273 const gp_Ax2& theOrientation,
274 const Standard_Real theHeight,
275 const Standard_Real theAngle,
276 const Graphic3d_TextPath theTp,
277 const Graphic3d_HorizontalTextAlignment theHTA,
278 const Graphic3d_VerticalTextAlignment theVTA,
279 const Standard_Boolean theToEvalMinMax = Standard_True,
280 const Standard_Boolean theHasOwnAnchor = Standard_True);
283 //! Dumps the content of me into the stream
284 Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
288 //! Creates a group in the structure <AStructure>.
289 Standard_EXPORT Graphic3d_Group(const Handle(Graphic3d_Structure)& theStructure);
291 //! Calls the Update method of the StructureManager which
292 //! contains the associated Structure of the Group <me>.
293 Standard_EXPORT void Update() const;
297 Handle(Graphic3d_TransformPers) myTrsfPers; //!< current transform persistence
298 Graphic3d_Structure* myStructure; //!< pointer to the parent structure
299 Graphic3d_BndBox4f myBounds; //!< bounding box
300 bool myIsClosed; //!< flag indicating closed volume
304 DEFINE_STANDARD_HANDLE(Graphic3d_Group, Standard_Transient)
306 #endif // _Graphic3d_Group_HeaderFile