0027818: Visualization - provide an interface to define highlight presentation properties
[occt.git] / src / Graphic3d / Graphic3d_Structure.hxx
CommitLineData
42cf5bc1 1// Created on: 1991-06-12
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_Structure_HeaderFile
18#define _Graphic3d_Structure_HeaderFile
19
20#include <Standard.hxx>
21#include <Standard_Type.hxx>
22
23#include <Graphic3d_CStructure.hxx>
24#include <Graphic3d_IndexedMapOfAddress.hxx>
42cf5bc1 25#include <Standard_Address.hxx>
26#include <Graphic3d_TypeOfStructure.hxx>
27#include <MMgt_TShared.hxx>
28#include <Standard_Boolean.hxx>
29#include <Standard_Integer.hxx>
30#include <Graphic3d_ZLayerId.hxx>
31#include <Graphic3d_SequenceOfHClipPlane.hxx>
32#include <Standard_Real.hxx>
42cf5bc1 33#include <Graphic3d_SequenceOfGroup.hxx>
34#include <Graphic3d_TypeOfConnection.hxx>
35#include <Graphic3d_MapOfStructure.hxx>
36#include <Graphic3d_TypeOfComposition.hxx>
825aa485 37#include <Graphic3d_TransformPers.hxx>
42cf5bc1 38#include <Graphic3d_TransModeFlags.hxx>
39#include <Graphic3d_BndBox4f.hxx>
40#include <Graphic3d_BndBox4d.hxx>
41#include <Graphic3d_Vertex.hxx>
42class Graphic3d_PriorityDefinitionError;
43class Graphic3d_StructureDefinitionError;
44class Graphic3d_TransformError;
45class Graphic3d_Group;
46class Graphic3d_StructureManager;
42cf5bc1 47class Graphic3d_DataStructureManager;
48class Bnd_Box;
49class gp_Pnt;
50class Graphic3d_Vector;
51
52
53class Graphic3d_Structure;
54DEFINE_STANDARD_HANDLE(Graphic3d_Structure, MMgt_TShared)
55
56//! This class allows the definition a graphic object.
57//! This graphic structure can be displayed,
58//! erased, or highlighted.
59//! This graphic structure can be connected with
60//! another graphic structure.
61//! Keywords: Structure, StructureManager, Display, Erase, Highlight,
62//! UnHighlight, Visible, Priority, Selectable, Visible,
63//! Visual, Connection, Ancestors, Descendants, Transformation
64class Graphic3d_Structure : public MMgt_TShared
65{
66
67public:
68
69
70 //! Creates a graphic object in the manager theManager.
71 //! It will appear in all the views of the visualiser.
42cf5bc1 72 //! The structure is not displayed when it is created.
73 Standard_EXPORT Graphic3d_Structure(const Handle(Graphic3d_StructureManager)& theManager);
74
75 //! Creates a shadow link to existing graphic object.
76 Standard_EXPORT Graphic3d_Structure(const Handle(Graphic3d_StructureManager)& theManager, const Handle(Graphic3d_Structure)& thePrs);
77
78 //! if WithDestruction == Standard_True then
79 //! suppress all the groups of primitives in the structure.
80 //! and it is mandatory to create a new group in <me>.
81 //! if WithDestruction == Standard_False then
82 //! clears all the groups of primitives in the structure.
83 //! and all the groups are conserved and empty.
84 //! They will be erased at the next screen update.
85 //! The structure itself is conserved.
86 //! The transformation and the attributes of <me> are conserved.
87 //! The childs of <me> are conserved.
88 Standard_EXPORT virtual void Clear (const Standard_Boolean WithDestruction = Standard_True);
89
90 //! Suppresses the structure <me>.
91 //! It will be erased at the next screen update.
e6f550da 92 Standard_EXPORT ~Graphic3d_Structure();
42cf5bc1 93
94 //! Displays the structure <me> in all the views of the visualiser.
95 Standard_EXPORT virtual void Display();
96
97 //! Returns the current display priority for the
98 //! structure <me>.
99 Standard_EXPORT Standard_Integer DisplayPriority() const;
100
101 //! Erases the structure <me> in all the views
102 //! of the visualiser.
103 Standard_EXPORT virtual void Erase();
104
8e5fb5ea 105 //! Highlights the structure in all the views with the given style
106 //! @param theStyle [in] the style (type of highlighting: box/color, color and opacity)
107 //! @param theToUpdateMgr [in] defines whether related computed structures will be
108 //! highlighted via structure manager or not
109 Standard_EXPORT void Highlight (const Handle(Graphic3d_HighlightStyle)& theStyle, const Standard_Boolean theToUpdateMgr = Standard_True);
42cf5bc1 110
111 //! Suppress the structure <me>.
112 //! It will be erased at the next screen update.
113 //! Warning: No more graphic operations in <me> after this call.
114 //! Category: Methods to modify the class definition
115 Standard_EXPORT void Remove();
116
117 //! Computes axis-aligned bounding box of a structure.
770fa4d4 118 Standard_EXPORT virtual void CalculateBoundBox();
42cf5bc1 119
120 //! If <theToSet> is Standard_True then <me> is infinite and
121 //! the MinMaxValues method method return :
122 //! theXMin = theYMin = theZMin = RealFirst().
123 //! theXMax = theYMax = theZMax = RealLast().
124 //! By default, <me> is not infinite but empty.
125 Standard_EXPORT void SetInfiniteState (const Standard_Boolean theToSet);
126
127 //! Modifies the order of displaying the structure.
128 //! Values are between 0 and 10.
129 //! Structures are drawn according to their display priorities
130 //! in ascending order.
131 //! A structure of priority 10 is displayed the last and appears over the others.
132 //! The default value is 5.
133 //! Category: Methods to modify the class definition
134 //! Warning: If <me> is displayed then the SetDisplayPriority
135 //! method erase <me> and display <me> with the
136 //! new priority.
137 //! Raises PriorityDefinitionError if <Priority> is
138 //! greater than 10 or a negative value.
139 Standard_EXPORT void SetDisplayPriority (const Standard_Integer Priority);
140
141 //! Reset the current priority of the structure to the
142 //! previous priority.
143 //! Category: Methods to modify the class definition
144 //! Warning: If <me> is displayed then the SetDisplayPriority
145 //! method erase <me> and display <me> with the
146 //! previous priority.
147 Standard_EXPORT void ResetDisplayPriority();
148
149 //! Set Z layer ID for the structure. The Z layer mechanism
150 //! allows to display structures presented in higher layers in overlay
151 //! of structures in lower layers by switching off z buffer depth
152 //! test between layers
153 Standard_EXPORT void SetZLayer (const Graphic3d_ZLayerId theLayerId);
154
155 //! Get Z layer ID of displayed structure. The method
156 //! returns -1 if the structure has no ID (deleted from graphic driver).
157 Standard_EXPORT Graphic3d_ZLayerId GetZLayer() const;
158
159 //! Changes a sequence of clip planes slicing the structure on rendering.
160 //! @param thePlanes [in] the set of clip planes.
3202bf1e 161 Standard_EXPORT void SetClipPlanes (const Handle(Graphic3d_SequenceOfHClipPlane)& thePlanes);
42cf5bc1 162
163 //! Get clip planes slicing the structure on rendering.
164 //! @return set of clip planes.
3202bf1e 165 Standard_EXPORT const Handle(Graphic3d_SequenceOfHClipPlane)& ClipPlanes() const;
2831708b 166
42cf5bc1 167 //! Modifies the visibility indicator to Standard_True or
168 //! Standard_False for the structure <me>.
169 //! The default value at the definition of <me> is
170 //! Standard_True.
171 Standard_EXPORT void SetVisible (const Standard_Boolean AValue);
172
173 //! Modifies the visualisation mode for the structure <me>.
174 Standard_EXPORT virtual void SetVisual (const Graphic3d_TypeOfStructure AVisual);
175
176 //! Modifies the minimum and maximum zoom coefficients
177 //! for the structure <me>.
178 //! The default value at the definition of <me> is unlimited.
179 //! Category: Methods to modify the class definition
180 //! Warning: Raises StructureDefinitionError if <LimitInf> is
181 //! greater than <LimitSup> or if <LimitInf> or
182 //! <LimitSup> is a negative value.
183 Standard_EXPORT void SetZoomLimit (const Standard_Real LimitInf, const Standard_Real LimitSup);
184
185 //! marks the structure <me> representing wired structure needed for
186 //! highlight only so it won't be added to BVH tree.
187 //! Category: Methods to modify the class definition
188 Standard_EXPORT void SetIsForHighlight (const Standard_Boolean isForHighlight);
189
190 //! Suppresses the highlight for the structure <me>
191 //! in all the views of the visualiser.
192 Standard_EXPORT void UnHighlight();
193
194 Standard_EXPORT virtual void Compute();
195
196 //! Returns the new Structure defined for the new visualization
197 Standard_EXPORT virtual Handle(Graphic3d_Structure) Compute (const Handle(Graphic3d_DataStructureManager)& aProjector);
198
199 //! Returns the new Structure defined for the new visualization
1f7f5a90 200 Standard_EXPORT virtual Handle(Graphic3d_Structure) Compute (const Handle(Graphic3d_DataStructureManager)& theProjector,
201 const Handle(Geom_Transformation)& theTrsf);
42cf5bc1 202
203 //! Returns the new Structure defined for the new visualization
204 Standard_EXPORT virtual void Compute (const Handle(Graphic3d_DataStructureManager)& aProjector, Handle(Graphic3d_Structure)& aStructure);
205
206 //! Returns the new Structure defined for the new visualization
1f7f5a90 207 Standard_EXPORT virtual void Compute (const Handle(Graphic3d_DataStructureManager)& theProjector,
208 const Handle(Geom_Transformation)& theTrsf,
209 Handle(Graphic3d_Structure)& theStructure);
210
42cf5bc1 211 //! Forces a new construction of the structure <me>
212 //! if <me> is displayed and TOS_COMPUTED.
213 Standard_EXPORT void ReCompute();
214
215 //! Forces a new construction of the structure <me>
216 //! if <me> is displayed in <aProjetor> and TOS_COMPUTED.
217 Standard_EXPORT void ReCompute (const Handle(Graphic3d_DataStructureManager)& aProjector);
218
219 //! Returns Standard_True if the structure <me> contains
220 //! Polygons, Triangles or Quadrangles.
221 Standard_EXPORT Standard_Boolean ContainsFacet() const;
2831708b 222
42cf5bc1 223 //! Returns the groups sequence included in the structure <me> (internal storage).
224 Standard_EXPORT const Graphic3d_SequenceOfGroup& Groups() const;
225
226 //! Returns the current number of groups in the
227 //! structure <me>.
228 Standard_EXPORT Standard_Integer NumberOfGroups() const;
229
230 //! Append new group to this structure.
231 Standard_EXPORT Handle(Graphic3d_Group) NewGroup();
232
233 //! Returns the highlight color for the Highlight method
234 //! with the highlight method TOHM_COLOR or TOHM_BOUNDBOX.
8e5fb5ea 235 Standard_EXPORT const Handle(Graphic3d_HighlightStyle)& HighlightStyle() const;
42cf5bc1 236
237 //! Returns Standard_True if the structure <me> is deleted.
238 //! <me> is deleted after the call Remove (me).
239 Standard_EXPORT Standard_Boolean IsDeleted() const;
240
241 //! Returns the display indicator for the structure <me>.
242 Standard_EXPORT virtual Standard_Boolean IsDisplayed() const;
243
244 //! Returns Standard_True if the structure <me> is empty.
245 //! Warning: A structure is empty if :
246 //! it do not have group or all the groups are empties
247 //! and it do not have descendant or all the descendants
248 //! are empties.
249 Standard_EXPORT Standard_Boolean IsEmpty() const;
250
251 //! Returns Standard_True if the structure <me> is infinite.
252 Standard_EXPORT Standard_Boolean IsInfinite() const;
253
254 //! Returns the highlight indicator for the structure <me>.
255 Standard_EXPORT virtual Standard_Boolean IsHighlighted() const;
256
42cf5bc1 257 //! Returns Standard_True if the structure <me> is transformed.
258 //! <=> The transformation != Identity.
259 Standard_EXPORT Standard_Boolean IsTransformed() const;
260
261 //! Returns the visibility indicator for the structure <me>.
262 Standard_EXPORT Standard_Boolean IsVisible() const;
2831708b 263
42cf5bc1 264 //! Returns the coordinates of the boundary box of the structure <me>.
265 //! If <theToIgnoreInfiniteFlag> is TRUE, the method returns actual graphical
266 //! boundaries of the Graphic3d_Group components. Otherwise, the
267 //! method returns boundaries taking into account infinite state
268 //! of the structure. This approach generally used for application
269 //! specific fit operation (e.g. fitting the model into screen,
270 //! not taking into accout infinite helper elements).
271 //! Warning: If the structure <me> is empty then the empty box is returned,
272 //! If the structure <me> is infinite then the whole box is returned.
273 Standard_EXPORT Bnd_Box MinMaxValues (const Standard_Boolean theToIgnoreInfiniteFlag = Standard_False) const;
2831708b 274
42cf5bc1 275 //! Returns the visualisation mode for the structure <me>.
276 Standard_EXPORT Graphic3d_TypeOfStructure Visual() const;
277
278 //! Returns Standard_True if the connection is possible between
279 //! <AStructure1> and <AStructure2> without a creation
280 //! of a cycle.
281 //!
282 //! It's not possible to call the method
283 //! AStructure1->Connect (AStructure2, TypeOfConnection)
284 //! if
285 //! - the set of all ancestors of <AStructure1> contains
286 //! <AStructure1> and if the
287 //! TypeOfConnection == TOC_DESCENDANT
288 //! - the set of all descendants of <AStructure1> contains
289 //! <AStructure2> and if the
290 //! TypeOfConnection == TOC_ANCESTOR
291 Standard_EXPORT static Standard_Boolean AcceptConnection (const Handle(Graphic3d_Structure)& AStructure1, const Handle(Graphic3d_Structure)& AStructure2, const Graphic3d_TypeOfConnection AType);
292
293 //! Returns the group of structures to which <me> is connected.
294 Standard_EXPORT void Ancestors (Graphic3d_MapOfStructure& SG) const;
295
296 //! If Atype is TOC_DESCENDANT then add <AStructure>
297 //! as a child structure of <me>.
298 //! If Atype is TOC_ANCESTOR then add <AStructure>
299 //! as a parent structure of <me>.
300 //! The connection propagates Display, Highlight, Erase,
301 //! Remove, and stacks the transformations.
302 //! No connection if the graph of the structures
303 //! contains a cycle and <WithCheck> is Standard_True;
304 Standard_EXPORT void Connect (const Handle(Graphic3d_Structure)& AStructure, const Graphic3d_TypeOfConnection AType, const Standard_Boolean WithCheck = Standard_False);
305
306 //! Returns the group of structures connected to <me>.
307 Standard_EXPORT void Descendants (Graphic3d_MapOfStructure& SG) const;
308
309 //! Suppress the connection between <AStructure> and <me>.
310 Standard_EXPORT void Disconnect (const Handle(Graphic3d_Structure)& AStructure);
311
312 //! If Atype is TOC_DESCENDANT then suppress all
313 //! the connections with the child structures of <me>.
314 //! If Atype is TOC_ANCESTOR then suppress all
315 //! the connections with the parent structures of <me>.
316 Standard_EXPORT void DisconnectAll (const Graphic3d_TypeOfConnection AType);
317
318 //! Returns <ASet> the group of structures :
319 //! - directly or indirectly connected to <AStructure> if the
320 //! TypeOfConnection == TOC_DESCENDANT
321 //! - to which <AStructure> is directly or indirectly connected
322 //! if the TypeOfConnection == TOC_ANCESTOR
323 Standard_EXPORT static void Network (const Handle(Graphic3d_Structure)& AStructure, const Graphic3d_TypeOfConnection AType, Graphic3d_MapOfStructure& ASet);
324
325 Standard_EXPORT void SetOwner (const Standard_Address Owner);
326
327 Standard_EXPORT Standard_Address Owner() const;
328
329 Standard_EXPORT void SetHLRValidation (const Standard_Boolean AFlag);
330
331 Standard_EXPORT Standard_Boolean HLRValidation() const;
6bd94e0d 332
1f7f5a90 333 //! Return local transformation.
334 const Handle(Geom_Transformation)& Transformation() const { return myCStructure->Transformation(); }
335
336 //! Modifies the current local transformation
337 Standard_EXPORT void SetTransformation (const Handle(Geom_Transformation)& theTrsf);
338
339 Standard_DEPRECATED("This method is deprecated - SetTransformation() should be called instead")
340 void Transform (const Handle(Geom_Transformation)& theTrsf) { SetTransformation (theTrsf); }
778cd667 341
342 //! Modifies the current transform persistence (pan, zoom or rotate)
343 Standard_EXPORT void SetTransformPersistence (const Handle(Graphic3d_TransformPers)& theTrsfPers);
825aa485 344
345 //! @return transform persistence of the presentable object.
778cd667 346 const Handle(Graphic3d_TransformPers)& TransformPersistence() const { return myCStructure->TransformPersistence(); }
825aa485 347
42cf5bc1 348 //! Sets if the structure location has mutable nature (content or location will be changed regularly).
349 Standard_EXPORT void SetMutable (const Standard_Boolean theIsMutable);
350
351 //! Returns true if structure has mutable nature (content or location are be changed regularly).
352 //! Mutable structure will be managed in different way than static onces.
353 Standard_EXPORT Standard_Boolean IsMutable() const;
354
355 Standard_EXPORT Graphic3d_TypeOfStructure ComputeVisual() const;
356
357 //! Clears the structure <me>.
358 Standard_EXPORT void GraphicClear (const Standard_Boolean WithDestruction);
359
360 Standard_EXPORT void GraphicConnect (const Handle(Graphic3d_Structure)& ADaughter);
361
362 Standard_EXPORT void GraphicDisconnect (const Handle(Graphic3d_Structure)& ADaughter);
8e5fb5ea 363
1f7f5a90 364 //! Internal method which sets new transformation without calling graphic manager callbacks.
365 Standard_EXPORT void GraphicTransform (const Handle(Geom_Transformation)& theTrsf);
8e5fb5ea 366
42cf5bc1 367 //! Returns the identification number of the structure <me>.
368 Standard_EXPORT Standard_Integer Identification() const;
369
370 //! Prints informations about the network associated
371 //! with the structure <AStructure>.
372 Standard_EXPORT static void PrintNetwork (const Handle(Graphic3d_Structure)& AStructure, const Graphic3d_TypeOfConnection AType);
373
374 //! Suppress the adress <APtr> in the list
375 //! of descendants or in the list of ancestors.
376 Standard_EXPORT void Remove (const Standard_Address APtr, const Graphic3d_TypeOfConnection AType);
377
378 Standard_EXPORT void SetComputeVisual (const Graphic3d_TypeOfStructure AVisual);
379
1f7f5a90 380 //! Transforms theX, theY, theZ with the transformation theTrsf.
381 Standard_EXPORT static void Transforms (const gp_Trsf& theTrsf,
382 const Standard_Real theX, const Standard_Real theY, const Standard_Real theZ,
383 Standard_Real& theNewX, Standard_Real& theNewY, Standard_Real& theNewZ);
384
42cf5bc1 385 //! Returns the low-level structure
778cd667 386 const Handle(Graphic3d_CStructure)& CStructure() const { return myCStructure; }
42cf5bc1 387
388friend class Graphic3d_Group;
389
390
92efcf78 391 DEFINE_STANDARD_RTTIEXT(Graphic3d_Structure,MMgt_TShared)
42cf5bc1 392
393protected:
394
42cf5bc1 395 //! Transforms boundaries with <theTrsf> transformation.
1f7f5a90 396 Standard_EXPORT static void TransformBoundaries (const gp_Trsf& theTrsf,
397 Standard_Real& theXMin, Standard_Real& theYMin, Standard_Real& theZMin,
398 Standard_Real& theXMax, Standard_Real& theYMax, Standard_Real& theZMax);
399
42cf5bc1 400 //! Appends new descendant structure.
401 Standard_EXPORT Standard_Boolean AppendDescendant (const Standard_Address theDescendant);
402
403 //! Removes the given descendant structure.
404 Standard_EXPORT Standard_Boolean RemoveDescendant (const Standard_Address theDescendant);
405
406 //! Appends new ancestor structure.
407 Standard_EXPORT Standard_Boolean AppendAncestor (const Standard_Address theAncestor);
408
409 //! Removes the given ancestor structure.
410 Standard_EXPORT Standard_Boolean RemoveAncestor (const Standard_Address theAncestor);
411
42cf5bc1 412private:
413
42cf5bc1 414 //! Suppress in the structure <me>, the group theGroup.
415 //! It will be erased at the next screen update.
416 Standard_EXPORT void Remove (const Handle(Graphic3d_Group)& theGroup);
417
418 //! Manages the number of groups in the structure <me>
419 //! which contains facet.
420 //! Polygons, Triangles or Quadrangles.
421 //! <ADelta> = +1 or -1
422 Standard_EXPORT void GroupsWithFacet (const Standard_Integer ADelta);
423
424 //! Returns the extreme coordinates found in the structure <me> without transformation applied.
425 Standard_EXPORT Graphic3d_BndBox4f minMaxCoord() const;
426
427 //! Gets untransformed bounding box from structure.
428 Standard_EXPORT void getBox (Graphic3d_BndBox4d& theBox, const Standard_Boolean theToIgnoreInfiniteFlag = Standard_False) const;
429
430 //! Adds transformed (with myCStructure->Transformation) bounding box of structure to theBox.
431 Standard_EXPORT void addTransformed (Graphic3d_BndBox4d& theBox, const Standard_Boolean theToIgnoreInfiniteFlag = Standard_False) const;
432
433 //! Returns the manager to which <me> is associated.
434 Standard_EXPORT Handle(Graphic3d_StructureManager) StructureManager() const;
435
50d06d8f 436 //! Calls the Update method of the StructureManager which contains the Structure <me>.
437 //! If theUpdateLayer is true then invalidates bounding box of ZLayer.
438 Standard_EXPORT void Update (const bool theUpdateLayer = false) const;
2831708b 439
440protected:
42cf5bc1 441
59ec40f8 442 Graphic3d_StructureManager* myStructureManager;
443 Graphic3d_StructureManager* myFirstStructureManager;
444 Graphic3d_TypeOfStructure myComputeVisual;
445
42cf5bc1 446 Handle(Graphic3d_CStructure) myCStructure;
447 Graphic3d_IndexedMapOfAddress myAncestors;
448 Graphic3d_IndexedMapOfAddress myDescendants;
42cf5bc1 449 Standard_Address myOwner;
450 Graphic3d_TypeOfStructure myVisual;
451
42cf5bc1 452};
453
42cf5bc1 454#endif // _Graphic3d_Structure_HeaderFile