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 <Standard.hxx>
21 #include <Standard_Type.hxx>
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 <MMgt_TShared.hxx>
30 #include <Standard_Real.hxx>
31 #include <Standard_CString.hxx>
32 #include <Graphic3d_Vertex.hxx>
33 #include <Quantity_PlaneAngle.hxx>
34 #include <Graphic3d_TextPath.hxx>
35 #include <Graphic3d_HorizontalTextAlignment.hxx>
36 #include <Graphic3d_VerticalTextAlignment.hxx>
37 #include <Graphic3d_TypeOfPrimitiveArray.hxx>
38 #include <Graphic3d_IndexBuffer.hxx>
39 #include <Graphic3d_Buffer.hxx>
40 #include <Graphic3d_BoundBuffer.hxx>
41 #include <Standard_Address.hxx>
42 #include <Graphic3d_GroupAspect.hxx>
44 #include <TCollection_ExtendedString.hxx>
46 class Graphic3d_Structure;
47 class Graphic3d_ArrayOfPrimitives;
49 //! This class allows the definition of groups
50 //! of primitives inside of graphic objects (presentations).
51 //! A group contains the primitives and attributes
52 //! for which the range is limited to this group.
53 //! The primitives of a group can be globally suppressed.
55 //! There are two main group usage models:
57 //! 1) Non-modifiable, or unbounded, group ('black box').
58 //! Developers can repeat a sequence of
59 //! SetPrimitivesAspect() with AddPrimitiveArray() methods arbitrary number of times
60 //! to define arbitrary number of primitive "blocks" each having individual apect values.
61 //! Any modification of such a group is forbidden, as aspects and primitives are mixed
62 //! in memory without any high-level logical structure, and any modification is very likely to result
63 //! in corruption of the group internal data.
64 //! It is necessary to recreate such a group as a whole when some attribute should be changed.
65 //! (for example, in terms of AIS it is necessary to re-Compute() the whole presentation each time).
66 //! 2) Bounded group. Developers should specify the necessary group aspects with help of
67 //! SetGroupPrimitivesAspect() and then add primitives to the group.
68 //! Such a group have simplified organization in memory (a single block of attributes
69 //! followed by a block of primitives) and therefore it can be modified, if it is necessary to
70 //! change parameters of some aspect that has already been set, using methods:
71 //! IsGroupPrimitivesAspectSet() to detect which aspect was set for primitives;
72 //! GroupPrimitivesAspect() to read current aspect values
73 //! and SetGroupPrimitivesAspect() to set new values.
75 //! Developers are strongly recommended to take all the above into account when filling Graphic3d_Group
76 //! with aspects and primitives and choose the group usage model beforehand out of application needs.
77 //! Note that some Graphic3d_Group class virtual methods contain only base implementation
78 //! that is extended by the descendant class in OpenGl package.
79 class Graphic3d_Group : public MMgt_TShared
81 friend class Graphic3d_Structure;
82 DEFINE_STANDARD_RTTIEXT(Graphic3d_Group,MMgt_TShared)
86 //! Supress all primitives and attributes of <me>.
87 //! To clear group without update in Graphic3d_StructureManager
88 //! pass Standard_False as <theUpdateStructureMgr>. This
89 //! used on context and viewer destruction, when the pointer
90 //! to structure manager in Graphic3d_Structure could be
91 //! already released (pointers are used here to avoid handle
93 Standard_EXPORT virtual void Clear (const Standard_Boolean theUpdateStructureMgr = Standard_True);
95 //! Supress the group <me> in the structure.
96 Standard_EXPORT virtual ~Graphic3d_Group();
98 //! Supress the group <me> in the structure.
99 //! Warning: No more graphic operations in <me> after this call.
100 //! Modifies the current modelling transform persistence (pan, zoom or rotate)
101 //! Get the current modelling transform persistence (pan, zoom or rotate)
102 Standard_EXPORT void Remove();
106 //! Return line aspect.
107 virtual Handle(Graphic3d_AspectLine3d) LineAspect() const = 0;
109 //! Assign line aspect to the group.
110 virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)& theAspect) = 0;
112 //! Return fill area aspect.
113 virtual Handle(Graphic3d_AspectFillArea3d) FillAreaAspect() const = 0;
115 //! Modifies the context for all the face primitives of the group.
116 virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect) = 0;
118 //! Return text aspect.
119 virtual Handle(Graphic3d_AspectText3d) TextAspect() const = 0;
121 //! Modifies the context for all the text primitives of the group.
122 virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectText3d)& theAspect) = 0;
124 //! Return marker aspect.
125 virtual Handle(Graphic3d_AspectMarker3d) MarkerAspect() const = 0;
127 //! Modifies the context for all the marker primitives of the group.
128 virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_AspectMarker3d)& theAspect) = 0;
130 //! Modifies the current context of the group to give
131 //! another aspect for all the line primitives created
132 //! after this call in the group.
133 virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)& theAspect) = 0;
135 //! Modifies the current context of the group to give
136 //! another aspect for all the face primitives created
137 //! after this call in the group.
138 virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect) = 0;
140 //! Modifies the current context of the group to give
141 //! another aspect for all the text primitives created
142 //! after this call in the group.
143 virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectText3d)& theAspect) = 0;
145 //! Modifies the current context of the group to give
146 //! another aspect for all the marker primitives created
147 //! after this call in the group.
148 virtual void SetPrimitivesAspect (const Handle(Graphic3d_AspectMarker3d)& theAspect) = 0;
150 //! Returns TRUE if aspect is set for the group.
151 Standard_EXPORT Standard_Boolean IsGroupPrimitivesAspectSet (const Graphic3d_GroupAspect theAspect) const;
153 //! Returns the context of all the primitives of the group.
154 Standard_EXPORT void GroupPrimitivesAspect (const Handle(Graphic3d_AspectLine3d)& theAspLine,
155 const Handle(Graphic3d_AspectText3d)& theAspText,
156 const Handle(Graphic3d_AspectMarker3d)& theAspMarker,
157 const Handle(Graphic3d_AspectFillArea3d)& theAspFill) const;
159 //! Returns the last inserted context in the group for each kind of primitives.
160 void PrimitivesAspect (const Handle(Graphic3d_AspectLine3d)& theAspLine,
161 const Handle(Graphic3d_AspectText3d)& theAspText,
162 const Handle(Graphic3d_AspectMarker3d)& theAspMarker,
163 const Handle(Graphic3d_AspectFillArea3d)& theAspFill) const
165 GroupPrimitivesAspect (theAspLine, theAspText, theAspMarker, theAspFill);
170 //! Creates the string <AText> at position <APoint>.
171 //! The 3D point of attachment is projected. The text is
172 //! written in the plane of projection.
173 //! The attributes are given with respect to the plane of
175 //! AHeight : Height of text.
176 //! (Relative to the Normalized Projection
177 //! Coordinates (NPC) Space).
178 //! AAngle : Orientation of the text
179 //! (with respect to the horizontal).
180 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);
182 //! Creates the string <AText> at position <APoint>.
183 //! The 3D point of attachment is projected. The text is
184 //! written in the plane of projection.
185 //! The attributes are given with respect to the plane of
187 //! AHeight : Height of text.
188 //! (Relative to the Normalized Projection
189 //! Coordinates (NPC) Space).
190 //! The other attributes have the following default values:
194 //! AVta : VTA_BOTTOM
195 Standard_EXPORT void Text (const Standard_CString AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Boolean EvalMinMax = Standard_True);
197 //! Creates the string <AText> at position <APoint>.
198 //! The 3D point of attachment is projected. The text is
199 //! written in the plane of projection.
200 //! The attributes are given with respect to the plane of
202 //! AHeight : Height of text.
203 //! (Relative to the Normalized Projection
204 //! Coordinates (NPC) Space).
205 //! AAngle : Orientation of the text
206 //! (with respect to the horizontal).
207 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);
209 //! Creates the string <AText> at position <APoint>.
210 //! The 3D point of attachment is projected. The text is
211 //! written in the plane of projection.
212 //! The attributes are given with respect to the plane of
214 //! AHeight : Height of text.
215 //! (Relative to the Normalized Projection
216 //! Coordinates (NPC) Space).
217 //! The other attributes have the following default values:
221 //! AVta : VTA_BOTTOM
222 Standard_EXPORT void Text (const TCollection_ExtendedString& AText, const Graphic3d_Vertex& APoint, const Standard_Real AHeight, const Standard_Boolean EvalMinMax = Standard_True);
224 //! Creates the string <theText> at orientation <theOrientation> in 3D space.
225 Standard_EXPORT virtual void Text (const Standard_CString theTextUtf,
226 const gp_Ax2& theOrientation,
227 const Standard_Real theHeight,
228 const Quantity_PlaneAngle theAngle,
229 const Graphic3d_TextPath theTp,
230 const Graphic3d_HorizontalTextAlignment theHTA,
231 const Graphic3d_VerticalTextAlignment theVTA,
232 const Standard_Boolean theToEvalMinMax = Standard_True,
233 const Standard_Boolean theHasOwnAnchor = Standard_True);
235 //! Creates the string <theText> at orientation <theOrientation> in 3D space.
236 Standard_EXPORT virtual void Text (const TCollection_ExtendedString& theText,
237 const gp_Ax2& theOrientation,
238 const Standard_Real theHeight,
239 const Quantity_PlaneAngle theAngle,
240 const Graphic3d_TextPath theTp,
241 const Graphic3d_HorizontalTextAlignment theHTA,
242 const Graphic3d_VerticalTextAlignment theVTA,
243 const Standard_Boolean theToEvalMinMax = Standard_True,
244 const Standard_Boolean theHasOwnAnchor = Standard_True);
247 //! Adds an array of primitives for display
248 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);
250 //! Adds an array of primitives for display
251 Standard_EXPORT void AddPrimitiveArray (const Handle(Graphic3d_ArrayOfPrimitives)& thePrim, const Standard_Boolean theToEvalMinMax = Standard_True);
253 //! Creates a primitive array with single marker using AddPrimitiveArray().
254 Standard_EXPORT void Marker (const Graphic3d_Vertex& thePoint, const Standard_Boolean theToEvalMinMax = Standard_True);
258 //! sets the stencil test to theIsEnabled state;
259 Standard_EXPORT virtual void SetStencilTestOptions (const Standard_Boolean theIsEnabled) = 0;
261 //! sets the flipping to theIsEnabled state.
262 Standard_EXPORT virtual void SetFlippingOptions (const Standard_Boolean theIsEnabled, const gp_Ax2& theRefPlane) = 0;
264 //! Returns true if the group contains Polygons, Triangles or Quadrangles.
265 bool ContainsFacet() const { return myContainsFacet; }
267 //! Returns Standard_True if the group <me> is deleted.
268 //! <me> is deleted after the call Remove (me) or the
269 //! associated structure is deleted.
270 Standard_EXPORT Standard_Boolean IsDeleted() const;
272 //! Returns Standard_True if the group <me> is empty.
273 Standard_EXPORT Standard_Boolean IsEmpty() const;
275 //! Returns the coordinates of the boundary box of the group.
276 Standard_EXPORT void MinMaxValues (Standard_Real& theXMin, Standard_Real& theYMin, Standard_Real& theZMin,
277 Standard_Real& theXMax, Standard_Real& theYMax, Standard_Real& theZMax) const;
279 //! Sets the coordinates of the boundary box of the group.
280 Standard_EXPORT void SetMinMaxValues (const Standard_Real theXMin, const Standard_Real theYMin, const Standard_Real theZMin,
281 const Standard_Real theXMax, const Standard_Real theYMax, const Standard_Real theZMax);
283 //! Returns boundary box of the group <me> without transformation applied,
284 const Graphic3d_BndBox4f& BoundingBox() const { return myBounds; }
286 //! Returns non-const boundary box of the group <me> without transformation applied,
287 Graphic3d_BndBox4f& ChangeBoundingBox() { return myBounds; }
289 //! Returns the structure containing the group <me>.
290 Standard_EXPORT Handle(Graphic3d_Structure) Structure() const;
292 //! Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
293 void SetClosed (const bool theIsClosed) { myIsClosed = theIsClosed; }
295 //! Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
296 bool IsClosed() const { return myIsClosed; }
300 //! Creates a group in the structure <AStructure>.
301 Standard_EXPORT Graphic3d_Group(const Handle(Graphic3d_Structure)& theStructure);
303 //! Calls the Update method of the StructureManager which
304 //! contains the associated Structure of the Group <me>.
305 Standard_EXPORT void Update() const;
309 Graphic3d_Structure* myStructure; //!< pointer to the parent structure
310 Graphic3d_BndBox4f myBounds; //!< bounding box
311 bool myIsClosed; //!< flag indicating closed volume
312 bool myContainsFacet; //!< flag indicating that this group contains face primitives
316 DEFINE_STANDARD_HANDLE(Graphic3d_Group, MMgt_TShared)
318 #endif // _Graphic3d_Group_HeaderFile