0027818: Visualization - provide an interface to define highlight presentation properties
[occt.git] / src / Graphic3d / Graphic3d_Structure.hxx
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>
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>
33 #include <Graphic3d_SequenceOfGroup.hxx>
34 #include <Graphic3d_TypeOfConnection.hxx>
35 #include <Graphic3d_MapOfStructure.hxx>
36 #include <Graphic3d_TypeOfComposition.hxx>
37 #include <Graphic3d_TransformPers.hxx>
38 #include <Graphic3d_TransModeFlags.hxx>
39 #include <Graphic3d_BndBox4f.hxx>
40 #include <Graphic3d_BndBox4d.hxx>
41 #include <Graphic3d_Vertex.hxx>
42 class Graphic3d_PriorityDefinitionError;
43 class Graphic3d_StructureDefinitionError;
44 class Graphic3d_TransformError;
45 class Graphic3d_Group;
46 class Graphic3d_StructureManager;
47 class Graphic3d_DataStructureManager;
48 class Bnd_Box;
49 class gp_Pnt;
50 class Graphic3d_Vector;
51
52
53 class Graphic3d_Structure;
54 DEFINE_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
64 class Graphic3d_Structure : public MMgt_TShared
65 {
66
67 public:
68
69   
70   //! Creates a graphic object in the manager theManager.
71   //! It will appear in all the views of the visualiser.
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.
92   Standard_EXPORT ~Graphic3d_Structure();
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   
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);
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.
118   Standard_EXPORT virtual void CalculateBoundBox();
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.
161   Standard_EXPORT void SetClipPlanes (const Handle(Graphic3d_SequenceOfHClipPlane)& thePlanes);
162   
163   //! Get clip planes slicing the structure on rendering.
164   //! @return set of clip planes.
165   Standard_EXPORT const Handle(Graphic3d_SequenceOfHClipPlane)& ClipPlanes() const;
166
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
200   Standard_EXPORT virtual Handle(Graphic3d_Structure) Compute (const Handle(Graphic3d_DataStructureManager)& theProjector,
201                                                                const Handle(Geom_Transformation)& theTrsf);
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
207   Standard_EXPORT virtual void Compute (const Handle(Graphic3d_DataStructureManager)& theProjector,
208                                         const Handle(Geom_Transformation)& theTrsf,
209                                         Handle(Graphic3d_Structure)& theStructure);
210
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;
222
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.
235   Standard_EXPORT const Handle(Graphic3d_HighlightStyle)& HighlightStyle() const;
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   
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;
263
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;
274
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;
332
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); }
341
342   //! Modifies the current transform persistence (pan, zoom or rotate)
343   Standard_EXPORT void SetTransformPersistence (const Handle(Graphic3d_TransformPers)& theTrsfPers);
344
345   //! @return transform persistence of the presentable object.
346   const Handle(Graphic3d_TransformPers)& TransformPersistence() const { return myCStructure->TransformPersistence(); }
347
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);
363
364   //! Internal method which sets new transformation without calling graphic manager callbacks.
365   Standard_EXPORT void GraphicTransform (const Handle(Geom_Transformation)& theTrsf);
366
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   
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
385   //! Returns the low-level structure
386   const Handle(Graphic3d_CStructure)& CStructure() const { return myCStructure; }
387
388 friend class Graphic3d_Group;
389
390
391   DEFINE_STANDARD_RTTIEXT(Graphic3d_Structure,MMgt_TShared)
392
393 protected:
394
395   //! Transforms boundaries with <theTrsf> transformation.
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
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
412 private:
413
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   
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;
439
440 protected:
441
442   Graphic3d_StructureManager* myStructureManager;
443   Graphic3d_StructureManager* myFirstStructureManager;
444   Graphic3d_TypeOfStructure   myComputeVisual;
445
446   Handle(Graphic3d_CStructure) myCStructure;
447   Graphic3d_IndexedMapOfAddress myAncestors;
448   Graphic3d_IndexedMapOfAddress myDescendants;
449   Standard_Address myOwner;
450   Graphic3d_TypeOfStructure myVisual;
451
452 };
453
454 #endif // _Graphic3d_Structure_HeaderFile