86df12385b69a6738f0fe58bde6cd30a5fa765ae
[occt.git] / src / SelectMgr / SelectMgr_ViewerSelector.hxx
1 // Created on: 1995-02-15
2 // Created by: Roberc Coublanc
3 // Copyright (c) 1995-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 _SelectMgr_ViewerSelector_HeaderFile
18 #define _SelectMgr_ViewerSelector_HeaderFile
19
20 #include <Standard_Transient.hxx>
21 #include <NCollection_DataMap.hxx>
22 #include <OSD_Chronometer.hxx>
23 #include <TColStd_SequenceOfInteger.hxx>
24 #include <TColStd_HArray1OfInteger.hxx>
25 #include <Select3D_BVHBuilder3d.hxx>
26 #include <SelectMgr_IndexedDataMapOfOwnerCriterion.hxx>
27 #include <SelectMgr_SelectingVolumeManager.hxx>
28 #include <SelectMgr_Selection.hxx>
29 #include <SelectMgr_SelectableObject.hxx>
30 #include <SelectMgr_SelectableObjectSet.hxx>
31 #include <SelectMgr_StateOfSelection.hxx>
32 #include <SelectMgr_ToleranceMap.hxx>
33 #include <Standard_OStream.hxx>
34
35 class SelectMgr_SelectionManager;
36 class SelectMgr_SensitiveEntitySet;
37 class SelectMgr_EntityOwner;
38 class Select3D_SensitiveEntity;
39
40 // resolve name collisions with X11 headers
41 #ifdef Status
42   #undef Status
43 #endif
44 typedef NCollection_DataMap<Handle(SelectMgr_SelectableObject), Handle(SelectMgr_SensitiveEntitySet) > SelectMgr_MapOfObjectSensitives;
45 typedef NCollection_DataMap<Handle(SelectMgr_SelectableObject), Handle(SelectMgr_SensitiveEntitySet) >::Iterator SelectMgr_MapOfObjectSensitivesIterator;
46
47 typedef NCollection_DataMap<Standard_Integer, SelectMgr_SelectingVolumeManager> SelectMgr_FrustumCache;
48
49 //! A framework to define finding, sorting the sensitive
50 //! primitives in a view. Services are also provided to
51 //! define the return of the owners of those primitives
52 //! selected. The primitives are sorted by criteria such
53 //! as priority of the primitive or its depth in the view
54 //! relative to that of other primitives.
55 //! Note that in 3D, the inheriting framework
56 //! StdSelect_ViewerSelector3d   is only to be used
57 //! if you do not want to use the services provided by
58 //! AIS.
59 //! Two tools are available to find and select objects
60 //! found at a given position in the view. If you want to
61 //! select the owners of all the objects detected at
62 //! point x,y,z you use the Init - More - Next - Picked
63 //! loop. If, on the other hand, you want to select only
64 //! one object detected at that point, you use the Init -
65 //! More - OnePicked loop. In this iteration, More is
66 //! used to see if an object was picked and
67 //! OnePicked, to get the object closest to the pick position.
68 //! Viewer selectors are driven by
69 //! SelectMgr_SelectionManager, and manipulate
70 //! the SelectMgr_Selection objects given to them by
71 //! the selection manager.
72 //!
73 //! Tolerances are applied to the entities in the following way:
74 //! 1. tolerance value stored in mytolerance will be used to calculate initial
75 //!    selecting frustum, which will be applied for intersection testing during
76 //!    BVH traverse;
77 //! 2. if tolerance of sensitive entity is less than mytolerance, the frustum for
78 //!    intersection detection will be resized according to its sensitivity.
79 class SelectMgr_ViewerSelector : public Standard_Transient
80 {
81   DEFINE_STANDARD_RTTIEXT(SelectMgr_ViewerSelector, Standard_Transient)
82   friend class SelectMgr_SelectionManager;
83 public:
84
85   //! Empties all the tables, removes all selections...
86   Standard_EXPORT void Clear();
87
88   //! returns the Sensitivity of picking
89   Standard_Real Sensitivity() const { return myTolerances.Tolerance(); }
90
91   //! Returns the pixel tolerance.
92   Standard_Integer PixelTolerance() const { return myTolerances.Tolerance(); }
93
94   //! Sets the pixel tolerance <theTolerance>.
95   Standard_EXPORT void SetPixelTolerance (const Standard_Integer theTolerance);
96
97   //! Sorts the detected entites by priority and distance.
98   //!          to be redefined if other criterion are used...
99   Standard_EXPORT void SortResult();
100
101   //! Returns the picked element with the highest priority,
102   //! and which is the closest to the last successful mouse position.
103   Handle(SelectMgr_EntityOwner) OnePicked() const
104   {
105     return mystored.IsEmpty()
106          ? Handle(SelectMgr_EntityOwner)()
107          : Picked (1);
108   }
109
110   //! Set preference of selecting one object for OnePicked() method:
111   //! - If True, objects with less depth (distance fron the view plane) are
112   //!   preferred regardless of priority (priority is used then to choose among
113   //!   objects with similar depth),
114   //! - If False, objects with higher priority are preferred regardless of the
115   //!   depth which is used to choose among objects of the same priority.
116   void SetPickClosest (const Standard_Boolean theToPreferClosest) { preferclosest = theToPreferClosest; }
117
118   //! Returns the number of detected owners.
119   Standard_Integer NbPicked() const { return mystored.Extent(); }
120
121   //! Clears picking results.
122   Standard_EXPORT void ClearPicked();
123
124   //! Returns the entity Owner for the object picked at specified position.
125   //! @param theRank rank of detected object within range 1...NbPicked()
126   Standard_EXPORT Handle(SelectMgr_EntityOwner) Picked (const Standard_Integer theRank) const;
127
128   //! Returns the Entity for the object picked at specified position.
129   //! @param theRank rank of detected object within range 1...NbPicked()
130   Standard_EXPORT const SelectMgr_SortCriterion& PickedData (const Standard_Integer theRank) const;
131
132   //! Returns the Entity for the object picked at specified position.
133   //! @param theRank rank of detected object within range 1...NbPicked()
134   const Handle(Select3D_SensitiveEntity)& PickedEntity (const Standard_Integer theRank) const { return PickedData (theRank).Entity; }
135
136   //! Returns the 3D point (intersection of picking axis with the object nearest to eye)
137   //! for the object picked at specified position.
138   //! @param theRank rank of detected object within range 1...NbPicked()
139   gp_Pnt PickedPoint (const Standard_Integer theRank) const { return PickedData (theRank).Point; }
140
141   Standard_EXPORT Standard_Boolean Contains (const Handle(SelectMgr_SelectableObject)& theObject) const;
142
143   //! Returns the default builder used to construct BVH of entity set.
144   const Handle(Select3D_BVHBuilder3d) EntitySetBuilder() { return myEntitySetBuilder; }
145
146   //! Sets the default builder used to construct BVH of entity set.
147   //! The new builder will be also assigned for already defined objects, but computed BVH trees will not be invalidated.
148   Standard_EXPORT void SetEntitySetBuilder (const Handle(Select3D_BVHBuilder3d)& theBuilder);
149
150   //! Returns the list of selection modes ModeList found in
151   //! this selector for the selectable object aSelectableObject.
152   //! Returns true if aSelectableObject is referenced inside
153   //! this selector; returns false if the object is not present
154   //! in this selector.
155   Standard_EXPORT Standard_Boolean Modes (const Handle(SelectMgr_SelectableObject)& theSelectableObject,
156                                           TColStd_ListOfInteger& theModeList,
157                                           const SelectMgr_StateOfSelection theWantedState = SelectMgr_SOS_Any) const;
158
159   //! Returns true if the selectable object
160   //! aSelectableObject having the selection mode aMode
161   //! is active in this selector.
162   Standard_EXPORT Standard_Boolean IsActive (const Handle(SelectMgr_SelectableObject)& theSelectableObject,
163                                              const Standard_Integer theMode) const;
164
165   //! Returns true if the selectable object
166   //! aSelectableObject having the selection mode aMode
167   //! is in this selector.
168   Standard_EXPORT Standard_Boolean IsInside (const Handle(SelectMgr_SelectableObject)& theSelectableObject,
169                                              const Standard_Integer theMode) const;
170
171   //! Returns the selection status Status of the selection aSelection.
172   Standard_EXPORT SelectMgr_StateOfSelection Status (const Handle(SelectMgr_Selection)& theSelection) const;
173
174   Standard_EXPORT TCollection_AsciiString Status (const Handle(SelectMgr_SelectableObject)& theSelectableObject) const;
175
176   //! Returns the list of active entity owners
177   Standard_EXPORT void ActiveOwners (NCollection_List<Handle(SelectMgr_EntityOwner)>& theOwners) const;
178
179   //! Adds new object to the map of selectable objects
180   Standard_EXPORT void AddSelectableObject (const Handle(SelectMgr_SelectableObject)& theObject);
181
182   //! Adds new selection to the object and builds its BVH tree
183   Standard_EXPORT void AddSelectionToObject (const Handle(SelectMgr_SelectableObject)& theObject,
184                                              const Handle(SelectMgr_Selection)& theSelection);
185
186   //! Moves existing object from set of not transform persistence objects
187   //! to set of transform persistence objects (or vice versa).
188   Standard_EXPORT void MoveSelectableObject (const Handle(SelectMgr_SelectableObject)& theObject);
189
190   //! Removes selectable object from map of selectable ones
191   Standard_EXPORT void RemoveSelectableObject (const Handle(SelectMgr_SelectableObject)& theObject);
192
193   //! Removes selection of the object and marks its BVH tree for rebuild
194   Standard_EXPORT void RemoveSelectionOfObject (const Handle(SelectMgr_SelectableObject)& theObject,
195                                                 const Handle(SelectMgr_Selection)& theSelection);
196
197   //! Marks BVH of selectable objects for rebuild. Parameter theIsForce set as true
198   //! guarantees that 1st level BVH for the viewer selector will be rebuilt during this call
199   Standard_EXPORT void RebuildObjectsTree (const Standard_Boolean theIsForce = Standard_False);
200
201   //! Marks BVH of sensitive entities of particular selectable object for rebuild. Parameter
202   //! theIsForce set as true guarantees that 2nd level BVH for the object given will be
203   //! rebuilt during this call
204   Standard_EXPORT void RebuildSensitivesTree (const Handle(SelectMgr_SelectableObject)& theObject,
205                                               const Standard_Boolean theIsForce = Standard_False);
206
207   //! Returns instance of selecting volume manager of the viewer selector
208   SelectMgr_SelectingVolumeManager& GetManager() { return mySelectingVolumeMgr; }
209
210   //! Return map of selectable objects.
211   const SelectMgr_SelectableObjectSet& SelectableObjects() const { return mySelectableObjects; }
212
213   //! Marks all added sensitive entities of all objects as non-selectable
214   Standard_EXPORT void ResetSelectionActivationStatus();
215
216   //! Is used for rectangular selection only
217   //! If theIsToAllow is false, only fully included sensitives will be detected, otherwise the algorithm will
218   //! mark both included and overlapped entities as matched
219   Standard_EXPORT void AllowOverlapDetection (const Standard_Boolean theIsToAllow);
220
221   //! Dumps the content of me into the stream
222   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
223
224 public:
225
226   //! Begins an iteration scanning for the owners detected at a position in the view.
227   Standard_DEPRECATED("Deprecated method Init()")
228   void Init() { initPicked(); }
229
230   //! Continues the interation scanning for the owners detected at a position in the view,
231   //! or continues the iteration scanning for the owner closest to the position in the view.
232   Standard_DEPRECATED("Deprecated method More()")
233   Standard_Boolean More() { return morePicked(); }
234
235   //! Returns the next owner found in the iteration. This is
236   //! a scan for the owners detected at a position in the view.
237   Standard_DEPRECATED("Deprecated method Next()")
238   void Next() { nextPicked(); }
239
240   //! Returns the current selected entity detected by the selector;
241   Standard_DEPRECATED("Deprecated method Picked()")
242   Standard_EXPORT Handle(SelectMgr_EntityOwner) Picked() const;
243
244   //! Initializes internal iterator for stored detected sensitive entities
245   Standard_DEPRECATED("Deprecated method InitDetected()")
246   void InitDetected() { initPicked(); }
247
248   //! Makes a step along the map of detected sensitive entities and their owners
249   Standard_DEPRECATED("Deprecated method NextDetected()")
250   void NextDetected() { nextPicked(); }
251
252   //! Returns true if iterator of map of detected sensitive entities has reached its end
253   Standard_DEPRECATED("Deprecated method MoreDetected()")
254   Standard_Boolean MoreDetected() { return morePicked(); }
255
256   //! Returns sensitive entity that was detected during the previous run of selection algorithm
257   Standard_DEPRECATED("Deprecated method DetectedEntity() should be replaced by DetectedEntity(int)")
258   Standard_EXPORT const Handle(Select3D_SensitiveEntity)& DetectedEntity() const;
259
260 protected:
261
262   Standard_EXPORT SelectMgr_ViewerSelector();
263
264   //! Traverses BVH containing all added selectable objects and
265   //! finds candidates for further search of overlap
266   Standard_EXPORT void TraverseSensitives();
267
268   //! Internal function that checks if there is possible overlap between some entity of selectable object theObject and
269   //! current selecting volume.
270   //! @param theObject [in] the selectable object for traversal.
271   //! @param theMgr [in] the (un)transformed copy of the selecting volume manager representing active selection frustum.
272   //! @param theCamera, theProjectionMat, theWorldViewMat [in] the source camera and matrices for theMgr given.
273   //! @param theViewportWidth, theViewportHeight [in] viewport (window) dimensions for evaluating 
274   //!        object's transformation persistence.
275   Standard_EXPORT void traverseObject (const Handle(SelectMgr_SelectableObject)& theObject,
276                                        const SelectMgr_SelectingVolumeManager& theMgr,
277                                        const Handle(Graphic3d_Camera)& theCamera,
278                                        const Graphic3d_Mat4d& theProjectionMat,
279                                        const Graphic3d_Mat4d& theWorldViewMat,
280                                        const Standard_Integer theViewportWidth,
281                                        const Standard_Integer theViewportHeight);
282
283   //! Internal function that checks if a particular sensitive
284   //! entity theEntity overlaps current selecting volume precisely
285   Standard_EXPORT void checkOverlap (const Handle(Select3D_SensitiveEntity)& theEntity,
286                                      const gp_GTrsf& theInversedTrsf,
287                                      SelectMgr_SelectingVolumeManager& theMgr);
288
289 private:
290
291   //! Checks if the entity given requires to scale current selecting frustum
292   Standard_Boolean isToScaleFrustum (const Handle(Select3D_SensitiveEntity)& theEntity);
293
294   //! In case if custom tolerance is set, this method will return sum of entity sensitivity and
295   //! custom tolerance. Otherwise, pure entity sensitivity factor will be returned.
296   Standard_Integer sensitivity (const Handle(Select3D_SensitiveEntity)& theEntity) const;
297
298   void Activate (const Handle(SelectMgr_Selection)& theSelection);
299
300   void Deactivate (const Handle(SelectMgr_Selection)& theSelection);
301
302   //! removes a Selection from the Selector
303   void Remove (const Handle(SelectMgr_Selection)& aSelection);
304
305   //! Internal function that checks if a current selecting frustum needs to be scaled and transformed for the entity and performs necessary calculations.
306   void computeFrustum (const Handle(Select3D_SensitiveEntity)& theEnt,
307                        const SelectMgr_SelectingVolumeManager& theMgrGlobal,
308                        const SelectMgr_SelectingVolumeManager& theMgrObject,
309                        const gp_GTrsf& theInvTrsf,
310                        SelectMgr_FrustumCache& theCachedMgrs,
311                        SelectMgr_SelectingVolumeManager& theResMgr);
312
313
314 private: // implementation of deprecated methods
315
316   //! Initializes internal iterator for stored detected sensitive entities
317   void initPicked() { myCurRank = 1; }
318
319   //! Makes a step along the map of detected sensitive entities and their owners
320   void nextPicked() { ++myCurRank; }
321
322   //! Returns true if iterator of map of detected sensitive entities has reached its end
323   Standard_Boolean morePicked() const
324   {
325     if (mystored.Extent() == 0) return Standard_False;
326     if (myCurRank == 0) return Standard_False;
327     return myCurRank <= myIndexes->Length();
328   }
329
330   //! Compute 3d position for detected entity.
331   void updatePoint3d (SelectMgr_SortCriterion& theCriterion,
332                       const SelectBasics_PickResult& thePickResult,
333                       const Handle(Select3D_SensitiveEntity)& theEntity,
334                       const gp_GTrsf& theInversedTrsf,
335                       const SelectMgr_SelectingVolumeManager& theMgr) const;
336
337 protected:
338
339   Standard_Boolean                              preferclosest;
340   Standard_Boolean                              myToUpdateTolerance;
341   SelectMgr_IndexedDataMapOfOwnerCriterion      mystored;
342   SelectMgr_SelectingVolumeManager              mySelectingVolumeMgr;
343   mutable SelectMgr_SelectableObjectSet         mySelectableObjects;
344   SelectMgr_ToleranceMap                        myTolerances;
345   NCollection_DataMap<Graphic3d_ZLayerId, Standard_Integer> myZLayerOrderMap;
346   Handle(Select3D_BVHBuilder3d)                 myEntitySetBuilder;
347   gp_Pnt                                        myCameraEye;
348   gp_Dir                                        myCameraDir;
349   Standard_Real                                 myCameraScale;
350
351 private:
352
353   Handle(TColStd_HArray1OfInteger)             myIndexes;
354   Standard_Integer                             myCurRank;
355   Standard_Boolean                             myIsLeftChildQueuedFirst;
356   Standard_Integer                             myEntityIdx;
357   SelectMgr_MapOfObjectSensitives              myMapOfObjectSensitives;
358
359 };
360
361 DEFINE_STANDARD_HANDLE(SelectMgr_ViewerSelector, Standard_Transient)
362
363 #endif