0027919: Visualization - support multiple transformation persistence groups within...
[occt.git] / src / Graphic3d / Graphic3d_Group.hxx
CommitLineData
42cf5bc1 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
42cf5bc1 20#include <Graphic3d_BndBox4f.hxx>
5b111128 21#include <Graphic3d_AspectLine3d.hxx>
22#include <Graphic3d_AspectFillArea3d.hxx>
23#include <Graphic3d_AspectText3d.hxx>
24#include <Graphic3d_AspectMarker3d.hxx>
bf5f0ca2 25#include <Graphic3d_MapOfAspectsToAspects.hxx>
42cf5bc1 26#include <Standard_CString.hxx>
27#include <Graphic3d_Vertex.hxx>
42cf5bc1 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>
ce01ec26 35#include <gp_Ax2.hxx>
36#include <TCollection_ExtendedString.hxx>
5b111128 37
38class Graphic3d_Structure;
42cf5bc1 39class Graphic3d_ArrayOfPrimitives;
8ed07085 40class Graphic3d_Text;
4e993e4d 41class Graphic3d_TransformPers;
42cf5bc1 42
42cf5bc1 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.
48//!
49//! There are two main group usage models:
50//!
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.
68//!
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.
ce01ec26 71//! Note that some Graphic3d_Group class virtual methods contain only base implementation
72//! that is extended by the descendant class in OpenGl package.
25e59720 73class Graphic3d_Group : public Standard_Transient
42cf5bc1 74{
59ec40f8 75 friend class Graphic3d_Structure;
25e59720 76 DEFINE_STANDARD_RTTIEXT(Graphic3d_Group,Standard_Transient)
42cf5bc1 77
78public:
79
54adc5e9 80 //! Suppress all primitives and attributes of <me>.
42cf5bc1 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
86 //! cross-reference);
87 Standard_EXPORT virtual void Clear (const Standard_Boolean theUpdateStructureMgr = Standard_True);
5b111128 88
54adc5e9 89 //! Suppress the group <me> in the structure.
59ec40f8 90 Standard_EXPORT virtual ~Graphic3d_Group();
5b111128 91
54adc5e9 92 //! Suppress the group <me> in the structure.
42cf5bc1 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();
5b111128 97
59ec40f8 98public:
99
b6472664 100 //! Return fill area aspect.
bf5f0ca2 101 virtual Handle(Graphic3d_Aspects) Aspects() const = 0;
5b111128 102
b6472664 103 //! Modifies the context for all the face primitives of the group.
bf5f0ca2 104 virtual void SetGroupPrimitivesAspect (const Handle(Graphic3d_Aspects)& theAspect) = 0;
5b111128 105
bf5f0ca2 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;
5b111128 108
eaac0866 109 //! Update presentation aspects after their modification.
110 virtual void SynchronizeAspects() = 0;
111
bf5f0ca2 112 //! Replace aspects specified in the replacement map.
113 virtual void ReplaceAspects (const Graphic3d_MapOfAspectsToAspects& theMap) = 0;
59ec40f8 114
8ed07085 115 //! Adds a text for display
116 Standard_EXPORT virtual void AddText (const Handle(Graphic3d_Text)& theTextParams,
117 const Standard_Boolean theToEvalMinMax = Standard_True);
118
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);
125
126 //! Adds an array of primitives for display
127 Standard_EXPORT void AddPrimitiveArray (const Handle(Graphic3d_ArrayOfPrimitives)& thePrim, const Standard_Boolean theToEvalMinMax = Standard_True);
128
8ed07085 129public:
130
131 //! sets the stencil test to theIsEnabled state;
132 Standard_EXPORT virtual void SetStencilTestOptions (const Standard_Boolean theIsEnabled) = 0;
133
134 //! sets the flipping to theIsEnabled state.
135 Standard_EXPORT virtual void SetFlippingOptions (const Standard_Boolean theIsEnabled, const gp_Ax2& theRefPlane) = 0;
136
4e993e4d 137 //! Return transformation persistence.
138 const Handle(Graphic3d_TransformPers)& TransformPersistence() const { return myTrsfPers; }
139
140 //! Set transformation persistence.
141 Standard_EXPORT virtual void SetTransformPersistence (const Handle(Graphic3d_TransformPers)& theTrsfPers);
142
8ed07085 143 //! Returns true if the group contains Polygons, Triangles or Quadrangles.
144 bool ContainsFacet() const { return myContainsFacet; }
145
146 //! Returns Standard_True if the group <me> is deleted.
147 //! <me> is deleted after the call Remove (me) or the
148 //! associated structure is deleted.
149 Standard_EXPORT Standard_Boolean IsDeleted() const;
150
151 //! Returns Standard_True if the group <me> is empty.
152 Standard_EXPORT Standard_Boolean IsEmpty() const;
153
154 //! Returns the coordinates of the boundary box of the group.
155 Standard_EXPORT void MinMaxValues (Standard_Real& theXMin, Standard_Real& theYMin, Standard_Real& theZMin,
156 Standard_Real& theXMax, Standard_Real& theYMax, Standard_Real& theZMax) const;
157
158 //! Sets the coordinates of the boundary box of the group.
159 Standard_EXPORT void SetMinMaxValues (const Standard_Real theXMin, const Standard_Real theYMin, const Standard_Real theZMin,
160 const Standard_Real theXMax, const Standard_Real theYMax, const Standard_Real theZMax);
161
162 //! Returns boundary box of the group <me> without transformation applied,
163 const Graphic3d_BndBox4f& BoundingBox() const { return myBounds; }
164
165 //! Returns non-const boundary box of the group <me> without transformation applied,
166 Graphic3d_BndBox4f& ChangeBoundingBox() { return myBounds; }
167
168 //! Returns the structure containing the group <me>.
169 Standard_EXPORT Handle(Graphic3d_Structure) Structure() const;
170
171 //! Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
172 void SetClosed (const bool theIsClosed) { myIsClosed = theIsClosed; }
173
174 //! Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
175 bool IsClosed() const { return myIsClosed; }
176
177//! @name obsolete methods
59ec40f8 178public:
5b111128 179
bbd92927 180 Standard_DEPRECATED("Deprecated method Marker(), pass Graphic3d_ArrayOfPoints to AddPrimitiveArray() instead")
181 Standard_EXPORT void Marker (const Graphic3d_Vertex& thePoint, const Standard_Boolean theToEvalMinMax = Standard_True);
182
42cf5bc1 183 //! Creates the string <AText> at position <APoint>.
184 //! The 3D point of attachment is projected. The text is
185 //! written in the plane of projection.
186 //! The attributes are given with respect to the plane of
187 //! projection.
188 //! AHeight : Height of text.
189 //! (Relative to the Normalized Projection
190 //! Coordinates (NPC) Space).
191 //! AAngle : Orientation of the text
192 //! (with respect to the horizontal).
8ed07085 193 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
194 Standard_EXPORT virtual void Text (const Standard_CString AText,
195 const Graphic3d_Vertex& APoint,
196 const Standard_Real AHeight,
197 const Standard_Real AAngle,
198 const Graphic3d_TextPath ATp,
199 const Graphic3d_HorizontalTextAlignment AHta,
200 const Graphic3d_VerticalTextAlignment AVta,
201 const Standard_Boolean EvalMinMax = Standard_True);
5b111128 202
42cf5bc1 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
8ed07085 216 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
217 Standard_EXPORT void Text (const Standard_CString AText,
218 const Graphic3d_Vertex& APoint,
219 const Standard_Real AHeight,
220 const Standard_Boolean EvalMinMax = Standard_True);
5b111128 221
42cf5bc1 222 //! Creates the string <AText> at position <APoint>.
223 //! The 3D point of attachment is projected. The text is
224 //! written in the plane of projection.
225 //! The attributes are given with respect to the plane of
226 //! projection.
227 //! AHeight : Height of text.
228 //! (Relative to the Normalized Projection
229 //! Coordinates (NPC) Space).
230 //! AAngle : Orientation of the text
231 //! (with respect to the horizontal).
8ed07085 232 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
233 Standard_EXPORT void Text (const TCollection_ExtendedString& AText,
234 const Graphic3d_Vertex& APoint,
235 const Standard_Real AHeight,
236 const Standard_Real AAngle,
237 const Graphic3d_TextPath ATp,
238 const Graphic3d_HorizontalTextAlignment AHta,
239 const Graphic3d_VerticalTextAlignment AVta,
240 const Standard_Boolean EvalMinMax = Standard_True);
5b111128 241
42cf5bc1 242 //! Creates the string <AText> at position <APoint>.
243 //! The 3D point of attachment is projected. The text is
244 //! written in the plane of projection.
245 //! The attributes are given with respect to the plane of
246 //! projection.
247 //! AHeight : Height of text.
248 //! (Relative to the Normalized Projection
249 //! Coordinates (NPC) Space).
250 //! The other attributes have the following default values:
251 //! AAngle : PI / 2.
252 //! ATp : TP_RIGHT
253 //! AHta : HTA_LEFT
254 //! AVta : VTA_BOTTOM
8ed07085 255 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
256 Standard_EXPORT void Text (const TCollection_ExtendedString& AText,
257 const Graphic3d_Vertex& APoint,
258 const Standard_Real AHeight,
259 const Standard_Boolean EvalMinMax = Standard_True);
5b111128 260
ce01ec26 261 //! Creates the string <theText> at orientation <theOrientation> in 3D space.
8ed07085 262 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
ce01ec26 263 Standard_EXPORT virtual void Text (const Standard_CString theTextUtf,
264 const gp_Ax2& theOrientation,
265 const Standard_Real theHeight,
ee2be2a8 266 const Standard_Real theAngle,
ce01ec26 267 const Graphic3d_TextPath theTp,
268 const Graphic3d_HorizontalTextAlignment theHTA,
269 const Graphic3d_VerticalTextAlignment theVTA,
3f1eb0ab 270 const Standard_Boolean theToEvalMinMax = Standard_True,
271 const Standard_Boolean theHasOwnAnchor = Standard_True);
ce01ec26 272
273 //! Creates the string <theText> at orientation <theOrientation> in 3D space.
8ed07085 274 Standard_DEPRECATED("Deprecated method Text() with obsolete arguments, use AddText() instead of it")
ce01ec26 275 Standard_EXPORT virtual void Text (const TCollection_ExtendedString& theText,
276 const gp_Ax2& theOrientation,
277 const Standard_Real theHeight,
ee2be2a8 278 const Standard_Real theAngle,
ce01ec26 279 const Graphic3d_TextPath theTp,
280 const Graphic3d_HorizontalTextAlignment theHTA,
281 const Graphic3d_VerticalTextAlignment theVTA,
3f1eb0ab 282 const Standard_Boolean theToEvalMinMax = Standard_True,
283 const Standard_Boolean theHasOwnAnchor = Standard_True);
ce01ec26 284
285
0904aa63 286 //! Dumps the content of me into the stream
bc73b006 287 Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
0904aa63 288
42cf5bc1 289protected:
290
42cf5bc1 291 //! Creates a group in the structure <AStructure>.
292 Standard_EXPORT Graphic3d_Group(const Handle(Graphic3d_Structure)& theStructure);
293
42cf5bc1 294 //! Calls the Update method of the StructureManager which
295 //! contains the associated Structure of the Group <me>.
296 Standard_EXPORT void Update() const;
297
59ec40f8 298protected:
42cf5bc1 299
4e993e4d 300 Handle(Graphic3d_TransformPers) myTrsfPers; //!< current transform persistence
59ec40f8 301 Graphic3d_Structure* myStructure; //!< pointer to the parent structure
302 Graphic3d_BndBox4f myBounds; //!< bounding box
303 bool myIsClosed; //!< flag indicating closed volume
304 bool myContainsFacet; //!< flag indicating that this group contains face primitives
42cf5bc1 305
306};
307
25e59720 308DEFINE_STANDARD_HANDLE(Graphic3d_Group, Standard_Transient)
42cf5bc1 309
310#endif // _Graphic3d_Group_HeaderFile