a4b6a3699f882d595f79ea5ac45c0ef56e115b38
[occt.git] / src / AIS / AIS_InteractiveObject.hxx
1 // Created on: 1996-12-11
2 // Created by: Robert COUBLANC
3 // Copyright (c) 1996-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 _AIS_InteractiveObject_HeaderFile
18 #define _AIS_InteractiveObject_HeaderFile
19
20 #include <Aspect_TypeOfFacingModel.hxx>
21 #include <AIS_KindOfInteractive.hxx>
22 #include <Graphic3d_NameOfMaterial.hxx>
23 #include <PrsMgr_TypeOfPresentation3d.hxx>
24 #include <SelectMgr_SelectableObject.hxx>
25 #include <TColStd_ListOfInteger.hxx>
26 #include <TColStd_ListOfTransient.hxx>
27 #include <Quantity_Color.hxx>
28
29 class AIS_InteractiveContext;
30 class Graphic3d_MaterialAspect;
31 class Prs3d_Presentation;
32 class Prs3d_BasicAspect;
33 class Bnd_Box;
34
35 //! Defines a class of objects with display and selection services.
36 //! Entities which are visualized and selected are
37 //! Interactive Objects. You can make use of classes of
38 //! standard Interactive Objects for which all necessary
39 //! methods have already been programmed, or you can
40 //! implement your own classes of Interactive Objects.
41 //! Specific attributes of entities such as arrow aspect for
42 //! dimensions must be loaded in a Drawer. This Drawer
43 //! is then applied to the Interactive Object in view.
44 //! There are four types of Interactive Object in AIS: the
45 //! construction element or Datum, the Relation, which
46 //! includes both dimensions and constraints, the Object,
47 //! and finally, when the object is of an unknown type, the None type.
48 //! Inside these categories, a signature, or index,
49 //! provides the possibility of additional characterization.
50 //! By default, the Interactive Object has a None type
51 //! and a signature of 0. If you want to give a particular
52 //! type and signature to your interactive object, you must
53 //! redefine the methods, Signature and Type.
54 //! Warning
55 //! In the case of attribute methods, methods for
56 //! standard attributes are virtual. They must be
57 //! redefined   by the inheriting classes. Setcolor for a
58 //! point and Setcolor for a plane, for example, do not
59 //! affect the same attributes in the Drawer.
60 class AIS_InteractiveObject : public SelectMgr_SelectableObject
61 {
62   friend class AIS_InteractiveContext;
63   DEFINE_STANDARD_RTTIEXT(AIS_InteractiveObject, SelectMgr_SelectableObject)
64 public:
65
66   //! Returns the kind of Interactive Object:
67   //! -   None
68   //! -   Datum
69   //! -   Relation
70   //! -   Object
71   //! By default, the   interactive object has a None type.
72   //! Because specific shapes entail different behavior
73   //! according to their sub-shapes, you may need to
74   //! create a Local Context. This will allow you to
75   //! specify the additional characteristics which you
76   //! need to handle these shapes.
77   Standard_EXPORT virtual AIS_KindOfInteractive Type() const;
78   
79   //! Specifies additional characteristics of Interactive
80   //! Objects. A signature is, in fact, an index with integer
81   //! values assigned different properties.
82   //! This method is frequently used in conjuction with
83   //! Type to give a particular type and signature to an
84   //! Interactive Object. By default, the Interactive Object
85   //! has a None type and a signature of 0. Among the
86   //! datums, this signature is attributed to the shape
87   //! The remaining datums have the following default signatures:
88   //! -   Point                   signature 1
89   //! -   Axis                     signature 2
90   //! -   Trihedron                signature 3
91   //! -   PlaneTrihedron            signature 4
92   //! -   Line                     signature 5
93   //! -   Circle                  signature 6
94   //! -   Plane                   signature 7.
95   Standard_EXPORT virtual Standard_Integer Signature() const;
96   
97   //! Informs the graphic context that the interactive Object
98   //! may be decomposed into sub-shapes for dynamic selection.
99   //! The most used Interactive Object is AIS_Shape.
100   //! Activation methods for standard selection modes are
101   //! proposed in the Interactive Context. These include
102   //! selection by vertex or by edges. For datums with the
103   //! same behavior as AIS_Shape, such as vetices and
104   //! edges, we must redefine the virtual method so that
105   //! AcceptShapeDecomposition returns false.
106   //! Rule for selection :
107   //! Mode 0 :  Selection of  the interactive Object itself
108   //! Mode 1 :  Selection of vertices
109   //! Mode 2 :  Selection Of Edges
110   //! Mode 3 :  Selection Of Wires
111   //! Mode 4 :  Selection Of Faces ...
112   virtual Standard_Boolean AcceptShapeDecomposition() const { return Standard_False; }
113
114   //! change the current facing model apply on polygons for
115   //! SetColor(), SetTransparency(), SetMaterial() methods
116   //! default facing model is Aspect_TOFM_TWO_SIDE. This mean that attributes is
117   //! applying both on the front and back face.
118   Standard_EXPORT void SetCurrentFacingModel (const Aspect_TypeOfFacingModel aModel = Aspect_TOFM_BOTH_SIDE);
119   
120   //! Returns the current facing model which is in effect.
121   Standard_EXPORT Aspect_TypeOfFacingModel CurrentFacingModel() const;
122   
123   Standard_EXPORT virtual void SetColor (const Quantity_Color& aColor);
124   
125   //! only the interactive obj knowns which Drawer attribute
126   //! is  affected by the color  (ex:  for a  wire, it's the
127   //! wireaspect field of the drawer, but  for a vertex, only
128   //! the point aspect field is affected by the color)
129   //! WARNING : Do not forget to set the corresponding fields
130   //! here (hasOwnColor and myOwnColor)
131   Standard_EXPORT virtual void SetColor (const Quantity_NameOfColor aColor);
132   
133   //! Removes color settings. Only the Interactive Object
134   //! knows which Drawer attribute is   affected by the color
135   //! setting. For a wire, for example, wire aspect is the
136   //! attribute affected. For a vertex, however, only point
137   //! aspect is affected by the color setting.
138   Standard_EXPORT virtual void UnsetColor();
139   
140   //! Allows you to provide the setting aValue for width.
141   //! Only the Interactive Object knows which Drawer
142   //! attribute is affected by the width setting.
143   Standard_EXPORT virtual void SetWidth (const Standard_Real aValue);
144   
145   Standard_EXPORT virtual void UnsetWidth();
146   
147   //! Returns true if the class of objects accepts the display mode aMode.
148   //! The interactive context can have a default mode of
149   //! representation for the set of Interactive Objects. This
150   //! mode may not be accepted by a given class of
151   //! objects. Consequently, this virtual method allowing us
152   //! to get information about the class in question must be implemented.
153   Standard_EXPORT virtual Standard_Boolean AcceptDisplayMode (const Standard_Integer aMode) const;
154   
155   //! Returns the default display mode. This method is to
156   //! be implemented when the main mode is not mode 0.
157   Standard_EXPORT virtual Standard_Integer DefaultDisplayMode() const;
158   
159   //! Updates the active presentation; if <AllModes> = Standard_True
160   //! all the presentations inside are recomputed.
161   //! IMPORTANT: It is preferable to call Redisplay method of
162   //! corresponding AIS_InteractiveContext instance for cases when it
163   //! is accessible. This method just redirects call to myCTXPtr,
164   //! so this class field must be up to date for proper result.
165   Standard_EXPORT void Redisplay (const Standard_Boolean AllModes = Standard_False);
166   
167   //! Sets the infinite state flag aFlage.
168   //! if   <aFlag>   = True  ,  the   interactiveObject  is
169   //! considered as infinite, i.e. its graphic presentations
170   //! are not taken in account for View FitAll...
171   Standard_EXPORT void SetInfiniteState (const Standard_Boolean aFlag = Standard_True);
172
173   //! Returns true if the interactive object is infinite. In this
174   //! case, its graphic presentations are not taken into
175   //! account in the fit-all view.
176   Standard_Boolean IsInfinite() const { return myInfiniteState; }
177
178   //! Indicates whether the Interactive Object has a pointer to an interactive context.
179   Standard_Boolean HasInteractiveContext() const { return myCTXPtr != NULL; }
180
181   //! Returns the context pointer to the interactive context.
182   Standard_EXPORT Handle(AIS_InteractiveContext) GetContext() const;
183   
184   //! Sets the interactive context aCtx and provides a link
185   //! to the default drawing tool or "Drawer" if there is none.
186   Standard_EXPORT virtual void SetContext (const Handle(AIS_InteractiveContext)& aCtx);
187   
188   //! Returns true if the object has an owner attributed to it.
189   //! The owner can be a shape for a set of sub-shapes or
190   //! a sub-shape for sub-shapes which it is composed of,
191   //! and takes the form of a transient.
192   Standard_EXPORT Standard_Boolean HasOwner() const;
193   
194   //! Returns the owner of the Interactive Object.
195   //! The owner can be a shape for a set of sub-shapes or
196   //! a sub-shape for sub-shapes which it is composed of,
197   //! and takes the form of a transient.
198   //! There are two types of owners:
199   //! -   Direct owners, decomposition shapes such as
200   //! edges, wires, and faces.
201   //! -   Users, presentable objects connecting to sensitive
202   //! primitives, or a shape which has been decomposed.
203   const Handle(Standard_Transient)& GetOwner() const { return myOwner; }
204
205   //! Allows you to attribute the owner theApplicativeEntity to
206   //! an Interactive Object. This can be a shape for a set of
207   //! sub-shapes or a sub-shape for sub-shapes which it
208   //! is composed of. The owner takes the form of a transient.
209   void SetOwner (const Handle(Standard_Transient)& theApplicativeEntity) { myOwner = theApplicativeEntity; }
210
211   //! Each Interactive Object has methods which allow us
212   //! to attribute an Owner to it in the form of a Transient.
213   //! This method removes the owner from the graphic entity.
214   Standard_EXPORT void ClearOwner();
215
216   //! Returns true if the Interactive Object has a display
217   //! mode setting. Otherwise, it is displayed in Neutral Point.
218   Standard_Boolean HasDisplayMode() const { return myDisplayMode != -1; }
219
220   //! Sets the display mode aMode for the interactive object.
221   //! An object can have its own temporary display mode,
222   //! which is different from that proposed by the interactive context.
223   //! The range of possibilities currently proposed is the following:
224   //! -   AIS_WireFrame
225   //! -   AIS_Shaded
226   //! This range can, however, be extended through the creation of new display modes.
227   Standard_EXPORT void SetDisplayMode (const Standard_Integer aMode);
228
229   //! Removes display mode settings from the interactive object.
230   void UnsetDisplayMode() { myDisplayMode = -1; }
231
232   //! Returns the display mode setting of the Interactive Object.
233   //! The range of possibilities is the following:
234   //! -   AIS_WireFrame
235   //! -   AIS_Shaded
236   //! This range can, however, be extended through the
237   //! creation of new display modes.
238   Standard_Integer DisplayMode() const { return myDisplayMode; }
239
240   //! Returns the selection priority setting. -1 indicates that there is none.
241   //! You can modify the selection priority of an owner to
242   //! make one entity more selectionable than another one.
243   //! The default selection priority for an owner is 5, for
244   //! example. To increase selection priority, choose a
245   //! setting between 5 and 10. An entity with priority 7 will
246   //! take priority over one with a setting of 6 if both
247   //! objects are selected at the same time.
248   //! You could give vertices priority 8, edges priority 7,
249   //! faces priority 6, and shapes priority 5. If a vertex, an
250   //! edge and a face are simultaneously detected during
251   //! selection, only the vertex will then be highlighted.
252   //! For trihedra, for example, the default priorities are the following four:
253   //! -   priority 1 - a trihedron
254   //! -   priority 5 - its origin
255   //! -   priority 3 - its axes
256   //! -   priority 2 - its planes
257   Standard_Integer SelectionPriority() const { return mySelPriority; }
258
259   //! Allows you to provide a setting thePriority for selection priority.
260   //! You can modify selection priority of an owner to make
261   //! one entity more selectionable than another one. The
262   //! default selection priority for an owner is 5, for
263   //! example. To increase selection priority, choose a
264   //! setting between 5 and 10. An entity with priority 7 will
265   //! take priority over one with a setting of 6.
266   void SetSelectionPriority (const Standard_Integer thePriority) { mySelPriority = thePriority; }
267
268   //! Removes the setting for selection priority. SelectionPriority then returns -1.
269   void UnsetSelectionPriority() { mySelPriority = -1; }
270
271   //! Returns true if there is a setting for selection priority.
272   //! You can modify selection priority of an owner to make
273   //! one entity more selectionable than another one. The
274   //! default selection priority for an owner is 5, for
275   //! example. To increase selection priority, choose a
276   //! setting between 5 and 10. An entity with priority 7 will
277   //! take priority over one with a setting of 6.
278   Standard_Boolean HasSelectionPriority() const { return mySelPriority != -1; }
279
280   //! Returns true if the Interactive Object is in highlight mode.
281   Standard_Boolean HasHilightMode() const { return myHilightMode != -1; }
282
283   //! Returns the setting for highlight mode.
284   //! At dynamic detection, the presentation echoed by the
285   //! Interactive Context, is by default the presentation
286   //! already on the screen. You can specify a Highlight
287   //! presentation mode which is valid no matter what the
288   //! active representation of the object. It makes no
289   //! difference whether this choice is temporary or
290   //! definitive.   To do this, we use the following functions:
291   //! -   SetHilightMode
292   //! -   UnSetHilightMode
293   //! In the case of a shape, whether it is visualized in
294   //! wireframe presentation or with shading, we want to
295   //! systematically highlight the wireframe presentation.
296   //! Consequently, we set the highlight mode to 0.
297   Standard_Integer HilightMode() const { return myHilightMode; }
298
299   //! Sets the highlight mode theMode for the interactive object.
300   //! If, for example, you want to systematically highlight
301   //! the wireframe presentation of a shape - whether
302   //! visualized in wireframe presentation or with shading -
303   //! you set the highlight mode to 0.
304   void SetHilightMode (const Standard_Integer theMode) { myHilightMode = theMode; }
305
306   //! Allows the user to take a given Prs for hilight
307   //! ex : for a shape which would be displayed in shading mode
308   //! the hilight Prs is the wireframe mode.
309   //! if No specific hilight mode is defined, the displayed Prs
310   //! will be the hilighted one.
311   void UnsetHilightMode() { myHilightMode = -1; }
312
313   //! Returns true if the Interactive Object has color.
314   Standard_Boolean HasColor() const { return hasOwnColor; }
315
316   //! Returns the color setting of the Interactive Object.
317   virtual Quantity_NameOfColor Color() const { return myOwnColor.Name(); }
318
319   virtual void Color (Quantity_Color& theColor) const { theColor = myOwnColor; }
320
321   //! Returns true if the Interactive Object has width.
322   Standard_Boolean HasWidth() const { return myOwnWidth != 0.0; }
323
324   //! Returns the width setting of the Interactive Object.
325   Standard_Real Width() const { return myOwnWidth; }
326
327   //! Returns true if the Interactive Object has a setting for material.
328   Standard_Boolean HasMaterial() const { return hasOwnMaterial; }
329
330   //! Returns the current material setting.
331   //! This will be on of the following materials:
332   //! -   Brass
333   //! -   Bronze
334   //! -   Gold
335   //! -   Pewter
336   //! -   Silver
337   //! -   Stone.
338   virtual Graphic3d_NameOfMaterial Material() const { return myOwnMaterial; }
339
340   //! Sets the name aName for material defining this
341   //! display attribute for the interactive object.
342   //! Material aspect determines shading aspect, color and
343   //! transparency of visible entities.
344   Standard_EXPORT virtual void SetMaterial (const Graphic3d_NameOfMaterial aName);
345   
346   //! Sets the material aMat defining this display attribute
347   //! for the interactive object.
348   //! Material aspect determines shading aspect, color and
349   //! transparency of visible entities.
350   Standard_EXPORT virtual void SetMaterial (const Graphic3d_MaterialAspect& aName);
351   
352   //! Removes the setting for material.
353   Standard_EXPORT virtual void UnsetMaterial();
354   
355   //! Attributes a setting aValue for transparency.
356   //! The transparency value should be between 0.0 and 1.0.
357   //! At 0.0 an object will be totally opaque, and at 1.0, fully transparent.
358   //! Warning At a value of 1.0, there may be nothing visible.
359   Standard_EXPORT virtual void SetTransparency (const Standard_Real aValue = 0.6);
360   
361   //! Returns true if there is a transparency setting.
362   Standard_Boolean IsTransparent() const { return myTransparency > 0.005; }
363
364   //! Returns the transparency setting.
365   //! This will be between 0.0 and 1.0.
366   //! At 0.0 an object will be totally opaque, and at 1.0, fully transparent.
367   Standard_EXPORT virtual Standard_Real Transparency() const;
368   
369   //! Removes the transparency setting. The object is opaque by default.
370   Standard_EXPORT virtual void UnsetTransparency();
371   
372   //! Clears settings provided by the drawing tool aDrawer.
373   Standard_EXPORT virtual void UnsetAttributes() Standard_OVERRIDE;
374
375   //! Returns TRUE when this object has a presentation
376   //! in the current DisplayMode()
377   Standard_EXPORT Standard_Boolean HasPresentation() const;
378   
379   //! Returns the current presentation of this object
380   //! according to the current DisplayMode()
381   Standard_EXPORT Handle(Prs3d_Presentation) Presentation() const;
382
383   //! Sets the graphic basic aspect to the current presentation.
384   Standard_EXPORT void SetAspect (const Handle(Prs3d_BasicAspect)& anAspect);
385   
386   //! Sets up polygon offsets for this object.
387   //! It modifies all existing presentations of <anObj> (if any),
388   //! so it is reasonable to call this method after <anObj> has been displayed.
389   //! Otherwise, Compute() method should pass Graphic3d_AspectFillArea3d
390   //! aspect from <myDrawer> to Graphic3d_Group to make polygon offsets work.
391   //!
392   //! <aMode> parameter can contain various combinations of
393   //! Aspect_PolygonOffsetMode enumeration elements (Aspect_POM_None means
394   //! that polygon offsets are not changed).
395   //! If <aMode> is different from Aspect_POM_Off and Aspect_POM_None, then <aFactor> and <aUnits>
396   //! arguments are used by graphic renderer to calculate a depth offset value:
397   //!
398   //! offset = <aFactor> * m + <aUnits> * r, where
399   //! m - maximum depth slope for the polygon currently being displayed,
400   //! r - minimum window coordinates depth resolution (implementation-specific).
401   //!
402   //! Deafult settings for OCC 3D viewer: mode = Aspect_POM_Fill, factor = 1., units = 0.
403   //!
404   //! Negative offset values move polygons closer to the viewport,
405   //! while positive values shift polygons away.
406   //! Consult OpenGL reference for details (glPolygonOffset function description).
407   //!
408   //! NOTE: This method has a side effect - it creates own shading aspect
409   //! if not yet created, so it is better to set up object material,
410   //! color, etc. first.
411   Standard_EXPORT virtual void SetPolygonOffsets (const Standard_Integer aMode, const Standard_ShortReal aFactor = 1.0, const Standard_ShortReal aUnits = 0.0);
412   
413   //! Returns Standard_True if <myDrawer> has non-null shading aspect
414   Standard_EXPORT virtual Standard_Boolean HasPolygonOffsets() const;
415   
416   //! Retrieves current polygon offsets settings from <myDrawer>.
417   Standard_EXPORT virtual void PolygonOffsets (Standard_Integer& aMode, Standard_ShortReal& aFactor, Standard_ShortReal& aUnits) const;
418   
419   //! Returns bounding box of object correspondingly to its current display mode.
420   Standard_EXPORT virtual void BoundingBox (Bnd_Box& theBndBox) Standard_OVERRIDE;
421
422   //! Enables or disables on-triangulation build of isolines according to the flag given.
423   Standard_EXPORT void SetIsoOnTriangulation (const Standard_Boolean theIsEnabled);
424
425   //! Synchronize presentation aspects after their modification.
426   //!
427   //! This method should be called after modifying primitive aspect properties (material, texture, shader)
428   //! so that modifications will take effect on already computed presentation groups (thus avoiding re-displaying the object).
429   Standard_EXPORT void SynchronizeAspects();
430
431 private:
432
433   Standard_EXPORT virtual Standard_Boolean RecomputeEveryPrs() const;
434
435   Standard_EXPORT void MustRecomputePrs (const Standard_Integer aMode) const;
436
437   Standard_EXPORT const TColStd_ListOfInteger& ListOfRecomputeModes() const;
438
439   Standard_EXPORT void SetRecomputeOk();
440
441 protected:
442
443   
444   //! The TypeOfPresention3d means that the interactive object
445   //! may have a presentation dependant of the view of Display.
446   Standard_EXPORT AIS_InteractiveObject(const PrsMgr_TypeOfPresentation3d aTypeOfPresentation3d = PrsMgr_TOP_AllView);
447
448   Standard_Real myTransparency;
449   Quantity_Color myOwnColor;
450   Graphic3d_NameOfMaterial myOwnMaterial;
451   Standard_Integer myHilightMode;
452   Standard_Real myOwnWidth;
453   Standard_Boolean myInfiniteState;
454   Standard_Boolean hasOwnColor;
455   Standard_Boolean hasOwnMaterial;
456   Aspect_TypeOfFacingModel myCurrentFacingModel;
457   Standard_Boolean myRecomputeEveryPrs;
458   TColStd_ListOfInteger myToRecomputeModes;
459
460 private:
461
462   AIS_InteractiveContext* myCTXPtr;
463   Handle(Standard_Transient) myOwner;
464   Standard_Integer mySelPriority;
465   Standard_Integer myDisplayMode;
466
467 };
468
469 DEFINE_STANDARD_HANDLE(AIS_InteractiveObject, SelectMgr_SelectableObject)
470
471 #endif // _AIS_InteractiveObject_HeaderFile