src/SelectMgr/SelectMgr.cdl

   1 -- Created on: 1995-02-06
   2 -- Created by: Mister rmi
   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 package SelectMgr
  18
  19         ---Purpose: SelectMgr manages the process of dynamic
  20         -- selection through the following services:
  21         -- -   activating and deactivating selection modes for Interactive Objects
  22         -- -   adding and removing viewer selectors
  23         -- -   definitions of abstract filter classes
  24         --  The principle of graphic selection consists in
  25         -- representing the objects which you want to select
  26         -- by a bounding box in the selection view. The object
  27         -- is selected when you use the mouse to designate
  28         -- the zone produced by the object.
  29         -- To realize this, the application creates a selection
  30         -- structure which is independent of the point of view.
  31         -- This structure is made up of sensitive primitives
  32         -- which have one owner object associated to each of
  33         -- them. The role of the sensitive primitive is to reply
  34         -- to the requests of the selection algorithm whereas
  35         -- the owner's purpose is to make the link between
  36         -- the sensitive primitive and the object to be selected.
  37         -- Each selection structure corresponds to a selection
  38         -- mode which defines the elements that can be selected.
  39         -- For example, to select a complete geometric model,
  40         -- the application can create a sensitive primitive for
  41         -- each face of the interactive object representing the
  42         -- geometric model. In this case, all the primitives
  43         -- share the same owner. On the other hand, to select
  44         -- an edge in a model, the application must create
  45         -- one sensitive primitive per edge.
  46         -- Example
  47         -- void
  48         -- InteractiveBox::ComputeSelection
  49         --       (const Handle(SelectMgr_Selection)& Sel,
  50         --        const Standard_Integer Mode){ switch(Mode){ case 0:
  51         -- // locating the whole box by making its faces sensitive ...
  52         --          {
  53         -- Handle(SelectMgr_EntityOwner)
  54         --  Ownr = new
  55         -- SelectMgr_EntityOwner(this,5);
  56         --        for(Standard_Integer
  57         -- I=1;I<=Nbfaces;I++){Sel->Add(new Select3D_SensitiveFace
  58         --                (Ownr,[array of the vertices] face I);
  59         --        break;
  60         --        }
  61         -- case 1:         // locates the   edges
  62         --          {
  63         --        for(Standard_Integer
  64         --  i=1;i<=12;i++){
  65         --                         // 1 owner per edge...
  66         --          Handle(mypk_EdgeOwner)
  67         --  Ownr = new
  68         -- mypk_EdgeOwner(this,i,6);
  69         --                         // 6->priority
  70         --          Sel->Add(new
  71         --          Select3D_SensitiveSegment
  72         --                   (Ownr,firstpt(i),lastpt(i));
  73         --        }
  74         --        }
  75         -- }
  76         -- The algorithms for creating selection structures
  77         -- store the sensitive primitives in a
  78         -- SelectMgr_Selection object. To do this, a set of
  79         -- ready-made sensitive primitives is supplied in the
  80         -- Select2D and Select3D packages. New sensitive
  81         -- primitives can be defined through inheritance
  82         -- from   SensitiveEntity. For the application to make
  83         -- its own objects selectable, it must define owner
  84         -- classes inheriting SelectMgr_EntityOwner.
  85         -- For any object inheriting from
  86         -- AIS_InteractiveObject, you redefine its
  87         -- ComputeSelection functions. In the example below
  88         -- there are different modes of selection on the
  89         -- topological shape contained within the interactive
  90         -- object -selection of the shape itself, the vertices,
  91         -- the edges, the wires, the faces.
  92         -- Example
  93         -- void
  94         -- MyPack_MyClass::ComputeSelection(
  95         --             const Handle(SelectMgr_Selection)& aSelection,
  96         --             const Standard_Integer aMode)
  97         -- {
  98         --    switch(aMode){
  99         --   case 0:
 100         --   StdSelect_BRepSelectionTool::Load(
 101         --      aSelection,this,myShape,TopAbs_SHAPE);
 102         --   break;
 103         --   }
 104         --   case 1:
 105         --   StdSelect_BRepSelectionTool::Load(
 106         --      aSelection,this,myShape,TopAbs_VERTEX);
 107         --   break;
 108         --   }
 109         --    case 2:
 110         --    StdSelect_BRepSelectionTool::Load(
 111         --       aSelection,this,myShape,TopAbs_EDGE);
 112         --    break;
 113         --    }
 114         --    case 3:
 115         --    StdSelect_BRepSelectionTool::Load(
 116         --       aSelection,this,myShape,TopAbs_WIRE);
 117         --    break;
 118         --    }
 119         --    case 4:
 120         --    StdSelect_BRepSelectionTool::Load(
 121         --       aSelection,this,myShape,TopAbs_FACE);
 122         --    break;
 123         --    }
 124         -- }
 125         -- The StdSelect_BRepSelectionTool object
 126         -- provides a high level service which will make the
 127         -- shape 'myShape' selectable when the
 128         -- AIS_InteractiveContext is asked to display your object.
 129         --   Note: The traditional way of highlighting selected entity
 130         -- owners adopted by the Open CASCADE library assumes that
 131         -- each entity owner highlights itself on its own. This approach
 132         -- has two drawbacks:
 133         --      -      each entity owner has to maintain its own
 134         --         Prs3d_Presentation object, that results in
 135         --         large memory overhead for thousands of owners;
 136         --      -      drawing selected owners one by one is not
 137         --         efficient from the OpenGL usage viewpoint.
 138         -- That is why a different method has been introduced. On the basis of
 139         -- SelectMgr_EntityOwner::IsAutoHilight() return value an AIS_LocalContext
 140         -- object either uses the traditional way of highlighting
 141         -- (IsAutoHilight() returned true) or groups such owners according
 142         -- to their Selectable Objects and finally calls
 143         -- SelectMgr_SelectableObject::HilightSelected()
 144         -- or ClearSelected(), passing a group of owners as an argument.
 145         -- Hence, an application can derive its own interactive object and
 146         -- redefine HilightSelected(), ClearSelected() and
 147         -- HilightOwnerWithColor() virtual methods to take advantage of
 148         -- such OpenGL technique as arrays of primitives. In any case,
 149         -- these methods should at least have empty implementation.
 150         -- The AIS_LocalContext::UpdateSelected(const Handle(AIS_InteratciveObject)&,
 151         -- Standard_Boolean) method can be used for efficient redrawing a
 152         -- selection presentation for a given interactive object from an
 153         -- application code.
 154         -- Additionally, the SelectMgr_SelectableObject::ClearSelections()
 155         -- method now accepts an optional boolean argument. This parameter
 156         -- defines whether all object selections should be flagged for
 157         -- further update or not. This improved method can be used to
 158         -- re-compute an object selection (without redisplaying the object
 159         -- completely) when some selection mode is activated not for the first time.
 160
 161 uses
 162     Standard,
 163     MMgt,
 164     TCollection,
 165     TColStd,
 166     TColgp,
 167     Quantity,
 168     Bnd,
 169     TopLoc,
 170     TopAbs,
 171     TopoDS,
 172     SelectBasics,
 173     PrsMgr,
 174     Prs3d,
 175     Graphic3d,
 176     gp
 177
 178
 179 is
 180
 181     enumeration StateOfSelection is
 182         SOS_Activated,
 183         SOS_Deactivated,
 184         SOS_Sleeping,
 185         SOS_Any,
 186         SOS_Unknown;
 187         ---Purpose: different state of a Selection in a ViewerSelector...
 188
 189
 190     enumeration TypeOfUpdate is TOU_Full,TOU_Partial,TOU_None;
 191         ---Purpose: Provides values for types of update, including
 192         -- -   full
 193         -- -   partial
 194         -- -   none.
 195
 196     enumeration TypeOfBVHUpdate is TBU_Add,
 197                                    TBU_Remove,
 198                                    TBU_Renew,
 199                                    TBU_Invalidate,
 200                                    TBU_None;
 201        ---Purpose:       Keeps track for BVH update state for each SelectMgr_Selection entity in a following way:
 202        -- - Add        : 2nd level BVH does not contain any of the selection's sensitive entities and they must be
 203        --                added;
 204        -- - Remove     : all sensitive entities of the selection must be removed from 2nd level BVH;
 205        -- - Renew      : 2nd level BVH already contains sensitives of the selection, but the its complete update
 206        --                and removal is required. Therefore, sensitives of the selection with this type of update
 207        --                must be removed from 2nd level BVH and added after recomputation.
 208        -- - Invalidate : the 2nd level BVH needs to be rebuilt;
 209        -- - None       : entities of the selection are up to date.
 210
 211     deferred class Filter;
 212
 213     deferred class CompositionFilter;
 214
 215     class AndFilter;
 216
 217     class OrFilter;
 218
 219
 220
 221
 222     class EntityOwner;
 223
 224     deferred class SelectableObject;
 225
 226     class  SelectionManager;
 227
 228     ---Category: instantiations of classes from TCollection...
 229
 230     class SequenceOfFilter instantiates Sequence from TCollection
 231     (Filter from SelectMgr);
 232
 233     class ListOfFilter instantiates List from TCollection
 234     (Filter from SelectMgr);
 235
 236     class SequenceOfOwner instantiates Sequence from TCollection
 237     (EntityOwner from SelectMgr);
 238
 239     class IndexedMapOfOwner instantiates IndexedMap from TCollection
 240     (EntityOwner from SelectMgr,MapTransientHasher from TColStd);
 241
 242     class SequenceOfSelector instantiates Sequence from TCollection
 243         (ViewerSelector from SelectMgr);
 244
 245     class DataMapOfObjectSelectors instantiates DataMap from TCollection
 246     (SelectableObject from SelectMgr,SequenceOfSelector,MapTransientHasher from TColStd);
 247
 248     private class IndexedDataMapOfOwnerCriterion
 249         instantiates IndexedDataMap from TCollection
 250                             (EntityOwner        from SelectBasics,
 251                              SortCriterion      from SelectMgr,
 252                              MapTransientHasher from TColStd);
 253
 254     private class SortCriterion;
 255
 256     pointer SOPtr to SelectableObject from SelectMgr;
 257
 258     imported CompareResults;
 259
 260     imported SelectableObjectSet;
 261     imported FrustumBuilder;
 262     imported BaseFrustum;
 263     imported Frustum;
 264     imported RectangularFrustum;
 265     imported TriangularFrustum;
 266     imported TriangularFrustumSet;
 267     imported SelectingVolumeManager;
 268     imported transient class Selection;
 269     imported SequenceOfSelection;
 270     imported SensitiveEntity;
 271     imported SensitiveEntitySet;
 272     imported transient class ViewerSelector;
 273
 274 end SelectMgr;