0024070: OpenGL capped object-level clipping planes

[occt.git] / src / SelectBasics / SelectBasics_SensitiveEntity.cdl

diff --git a/src/SelectBasics/SelectBasics_SensitiveEntity.cdl b/src/SelectBasics/SelectBasics_SensitiveEntity.cdl
index 687efec..2b234d3 100755 (executable)
--- a/src/SelectBasics/SelectBasics_SensitiveEntity.cdl
+++ b/src/SelectBasics/SelectBasics_SensitiveEntity.cdl
@@ -28,7 +28,8 @@ deferred class SensitiveEntity from SelectBasics inherits TShared from MMgt
 uses 
     EntityOwner,
     ListOfBox2d,
-    Array1OfPnt2d from TColgp, 
+    PickArgs,
+    Array1OfPnt2d from TColgp,
     Box2d from Bnd
 
 is
@@ -52,21 +53,49 @@ is
     ---Purpose: to be implemented specifically by each type of
     --          sensitive  primitive .
     --          
-    
-    Matches (me  :mutable; 
-             X,Y : Real from Standard;
-             aTol: Real from Standard;
-             DMin: out Real from Standard) 
-    returns Boolean
-    is deferred;
-    ---Level: Public 
-    ---Purpose: returns True if the object is very close to the
-    --          sensitive areas it gave to the selector...
-    --          returns the minimum distance found if no match;
-    --          
-    --          to be implemented specifically by each type of
-    --          sensitive  primitive .
-    
+
+    Matches (me : mutable;
+             thePickArgs : PickArgs from SelectBasics;
+             theMatchDMin : out Real from Standard;
+             theMatchDepth : out Real from Standard) returns Boolean is deferred;
+    ---Level: Public
+    ---Purpose: Checks whether the sensitive entity matches the picking detection
+    -- area (close to the picking line). This method takes into account depth
+    -- limits produced by abstract view: far/near planes, clippings.
+    -- Please port existing implementations of your picking detection, which
+    -- were done at Matches (X, Y, Tol, DMin) method to this one, introducing
+    -- the depth checks. Please note that the previous method is suppressed
+    -- and the virtual implementations are not used by OCC selection framework.
+    -- The porting procedure for simple sensitives (or if you are not interested
+    -- in implementing full scale depth checks) can be simplified to writing the
+    -- following code snippet:
+    -- @code
+    -- { // example code for porting descendants of Select3D_SensitiveEntity
+    --
+    --   // invoke implementation of obsolete matches method (if implemented)...
+    --   if (!Matches (thePickArgs.X(), thePickArgs.Y(), thePickArgs.Tolerance(), theMatchDMin))
+    --     return Standard_False;
+    --
+    --   // invoke your implementation of computing depth (if implemented)...
+    --   Standard_Real aDetectDepth = ComputeDepth (thePickArgs.PickLine());
+    --
+    --   return !thePickArgs.IsClipped(aDetectDepth);
+    -- }
+    -- @endcode
+    -- @param thePickArgs [in] the picking arguments.
+    -- @param theMatchDMin [out] the minimum distance on xy plane from point
+    -- of picking to center of gravity of the detected sub-part of sensitive
+    -- entity or the whole sensitive (e.g. used for resolving selection of
+    -- coinciding circles, selection will be set to the one whose center is
+    -- closest to the picking point).
+    -- @param theMatchDepth [out] the minimum detected depth: depth of the 
+    -- closest detected sub-part of sensitive entity (or the whole sensitive).
+    -- @return True if the sensitive matches the detection area.
+    -- This method is an entry point for picking detection framework.
+    -- The method is triggered when it is required to compose list of
+    -- detected sensitive entities. The sensitives are filtered out from
+    -- detection result if returned value is False. The passed entities are
+    -- then can be sorted by "theDetectDist", "theDetectDepth" parameters.
 
     Matches (me  :mutable; 
              XMin,YMin,XMax,YMax : Real from Standard;
@@ -96,10 +125,6 @@ is
     ---Purpose: returns True if able to give 3D information
     --          (Depth,...). See Select3D
     
-    Depth(me) returns Real from Standard is virtual;
-    ---Level: Internal 
-    ---Purpose:  Sort Selected entities according to depth...
-
     MaxBoxes(me) returns Integer is deferred;
     ---Purpose: returns the max number of boxes the entity is able to give
     --          at a time