0024070: OpenGL capped object-level clipping planes

Graphical clipping:
- Use "Graphic3d_ClipPlane" to defined clipping for PrsMgr_PresentableObject (local clipping), for V3d_View (global clipping).

Get rid of old implementations:
- Remove Visual3d_ClipPlane.
- Port V3d_Plane to Graphic3d_ClipPlane core.

Selection Sensitives:
- Port "Matches" method to add full set of arguments (SelectBasics_PickArgs), including min-max depth coming from selector.
- Get rid of transient data for pair Matches -> ComputeDepth.
- Extend SelectMgr_ViewerSelector::LoadResult to work with local clipping, add virtual callbacks to compute globa/local depth clipping for picking.

Capping rendering algorithm:
- Recursive rendering algorithm for OpenGl_Groups.
- Introduced Rendering filter for groups.

Clipping plane management in TKOpenGl:
- Added OpenGl_ClippingState to OpenGl_Context.

DRAWEXE commands:
- Ported "vclipplane" command for new approach.
- Added "vsettexturemode" command for changing texture details in views (enable / disable textures).

Correct DownCast syntax (compilation error)

Fix new compiler warnings

tests/bugs/vis/bug22906 migrated to the new vclipplane syntax

src/SelectBasics/FILES

@@ -0,0 +1 @@
+SelectBasics_PickArgs.hxx

src/SelectBasics/SelectBasics.cdl

@@ -69,6 +69,9 @@ is
     class ListOfSensitive instantiates List from TCollection 
     (SensitiveEntity);
 
+    imported PickArgs;
+    ---Purpose: Structure to provide all-in-one information on picking arguments
+    -- for "Matches" method of SelectBasics_SensitiveEntity.
 
     MaxOwnerPriority returns Integer;
     

src/SelectBasics/SelectBasics_PickArgs.hxx

@@ -0,0 +1,79 @@
+// Created on: 2013-09-04
+// Created by: Anton POLETAEV
+// Copyright (c) 2013 OPEN CASCADE SAS
+//
+// The content of this file is subject to the Open CASCADE Technology Public
+// License Version 65 (the "License") You may not use the content of this file
+// except in compliance with the License Please obtain a copy of the License
+// at http://www.opencascade.org and read it completely before using this file
+//
+// The Initial Developer of the Original Code is Open CASCADE SAS, having its
+// main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France
+//
+// The Original Code and all software distributed under the License is
+// distributed on an "AS IS" basis, without warranty of any kind, and the
+// Initial Developer hereby disclaims all such warranties, including without
+// limitation, any warranties of merchantability, fitness for a particular
+// purpose or non-infringement Please see the License for the specific terms
+// and conditions governing the rights and limitations under the License
+
+#ifndef _SelectBasics_PickArgs_HeaderFile
+#define _SelectBasics_PickArgs_HeaderFile
+
+#include <Standard_TypeDef.hxx>
+#include <gp_Lin.hxx>
+
+//! Structure to provide all-in-one information on picking arguments
+//! for "Matches" method of SelectBasics_SensitiveEntity.
+struct SelectBasics_PickArgs
+{
+public:
+
+  //! Constructor.
+  //! @param theX mouse picking coordinate on x-axis of selection coord space.
+  //! @param theY mouse picking coordinate on y-axis of selection coord space.
+  //! @param theTolerance x, y coordinate tolerance.
+  //! @param theDepthMin minimum picking depth in selection coord space.
+  //! @param theDepthMax maximum picking depth in selection coord space.
+  //! @param thePickingLine line going through picking point.
+  SelectBasics_PickArgs (const Standard_Real theX,
+                         const Standard_Real theY,
+                         const Standard_Real theTolerance,
+                         const Standard_Real theDepthMin,
+                         const Standard_Real theDepthMax,
+                         const gp_Lin& thePickingLine)
+  : myX (theX), myY (theY), myTolerance (theTolerance),
+    myDepthMin (theDepthMin), myDepthMax (theDepthMax),
+    myPickingLine (thePickingLine) {}
+
+public:
+
+  inline Standard_Real X() const { return myX; }
+
+  inline Standard_Real Y() const { return myY; }
+
+  inline Standard_Real Tolerance() const { return myTolerance; }
+
+  inline Standard_Real DepthMin() const { return myDepthMin; }
+
+  inline Standard_Real DepthMax() const { return myDepthMax; }
+
+  inline const gp_Lin& PickLine() const { return myPickingLine; }
+
+  //! @return True if passed depth lies outside valid depth range.
+  inline Standard_Boolean IsClipped(const Standard_Real theDepth) const
+  {
+    return (theDepth <= myDepthMin || theDepth >= myDepthMax);
+  }
+
+private:
+
+  Standard_Real myX;         //!< mouse picking coordinate on x-axis of selection coord space.
+  Standard_Real myY;         //!< mouse picking coordinate on y-axis of selection coord space.
+  Standard_Real myTolerance; //!< x, y coordinate tolerance
+  Standard_Real myDepthMin;  //!< minimum picking depth in selection coord space.
+  Standard_Real myDepthMax;  //!< maximum picking depth in selection coord space.
+  gp_Lin myPickingLine;      //!< line going through picking point
+};
+
+#endif

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

src/SelectBasics/SelectBasics_SensitiveEntity.cxx

@@ -39,7 +39,3 @@ void SelectBasics_SensitiveEntity
 
 const Handle(SelectBasics_EntityOwner)&  SelectBasics_SensitiveEntity
 ::OwnerId() const {return myOwnerId;}
-
-Standard_Real SelectBasics_SensitiveEntity::Depth() const
-{return 0.0;}
-