0028107: Visualization - provide a flexible interface to set custom hatch styles
[occt.git] / src / Graphic3d / Graphic3d_ClipPlane.hxx
1 // Created on: 2013-07-12
2 // Created by: Anton POLETAEV
3 // Copyright (c) 2013-2014 OPEN CASCADE SAS
4 //
5 // This file is part of Open CASCADE Technology software library.
6 //
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
12 //
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
15
16 #ifndef _Graphic3d_ClipPlane_HeaderFile
17 #define _Graphic3d_ClipPlane_HeaderFile
18
19 #include <Aspect_HatchStyle.hxx>
20 #include <gp_Pln.hxx>
21 #include <Graphic3d_AspectFillArea3d.hxx>
22 #include <Graphic3d_CappingFlags.hxx>
23 #include <Graphic3d_TextureMap.hxx>
24 #include <NCollection_Vec4.hxx>
25 #include <Standard_Macro.hxx>
26 #include <Standard_TypeDef.hxx>
27 #include <Standard_Transient.hxx>
28
29 //! Container for properties describing graphic driver clipping planes.
30 //! It is up to application to create instances of this class and specify its
31 //! properties. The instances are passed into graphic driver or other facilities
32 //! that implement clipping features (e.g. selection).
33 //! Depending on usage context the class can be used to specify:
34 //! - Global clipping applied over the whole scene.
35 //! - Object-level clipping applied for each particular object.
36 //! The plane equation is specified in "world" coordinate system.
37 //! Please note that the set of planes can define convex clipping volume.
38 //! Be aware that number of clip planes supported by OpenGl is implementation
39 //! dependent: at least 6 planes are available. Thus, take into account
40 //! number of clipping planes passed for rendering: the object planes plus
41 //! the view defined ones.
42 class Graphic3d_ClipPlane : public Standard_Transient
43 {
44 public:
45
46   typedef NCollection_Vec4<Standard_Real> Equation;
47
48   //! Default constructor.
49   //! Initializes clip plane container with the following properties:
50   //! - Equation (0.0, 0.0, 1.0, 0)
51   //! - IsOn (True),
52   //! - IsCapping (False),
53   //! - Material (Graphic3d_NOM_DEFAULT),
54   //! - Texture (NULL),
55   //! - HatchStyle (Aspect_HS_HORIZONTAL),
56   //! - IsHatchOn (False)
57   Standard_EXPORT Graphic3d_ClipPlane();
58
59   //! Copy constructor.
60   //! @param theOther [in] the copied plane.
61   Standard_EXPORT Graphic3d_ClipPlane(const Graphic3d_ClipPlane& theOther);
62
63   //! Construct clip plane for the passed equation.
64   //! By default the plane is on, capping is turned off.
65   //! @param theEquation [in] the plane equation.
66   Standard_EXPORT Graphic3d_ClipPlane (const Equation& theEquation);
67
68   //! Construct clip plane from the passed geometrical definition.
69   //! By default the plane is on, capping is turned off.
70   //! @param thePlane [in] the plane.
71   Standard_EXPORT Graphic3d_ClipPlane (const gp_Pln& thePlane);
72
73   //! Set plane equation by its geometrical definition.
74   //! The equation is specified in "world" coordinate system.
75   //! @param thePlane [in] the plane.
76   Standard_EXPORT void SetEquation (const gp_Pln& thePlane);
77
78   //! Set 4-component equation vector for clipping plane.
79   //! The equation is specified in "world" coordinate system.
80   //! @param theEquation [in] the XYZW (or "ABCD") equation vector.
81   Standard_EXPORT void SetEquation (const Equation& theEquation);
82
83   //! Get 4-component equation vector for clipping plane.
84   //! @return clipping plane equation vector.
85   const Equation& GetEquation() const
86   {
87     return myEquation;
88   }
89
90   //! Check that the clipping plane is turned on.
91   //! @return boolean flag indicating whether the plane is in on or off state.
92   Standard_Boolean IsOn() const
93   {
94     return myIsOn;
95   }
96
97   //! Change state of the clipping plane.
98   //! @param theIsOn [in] the flag specifying whether the graphic driver
99   //! clipping by this plane should be turned on or off.
100   Standard_EXPORT void SetOn(const Standard_Boolean theIsOn);
101
102   //! Change state of capping surface rendering.
103   //! @param theIsOn [in] the flag specifying whether the graphic driver should
104   //! perform rendering of capping surface produced by this plane. The graphic
105   //! driver produces this surface for convex graphics by means of stencil-test
106   //! and multi-pass rendering.
107   Standard_EXPORT void SetCapping(const Standard_Boolean theIsOn);
108
109   //! Check state of capping surface rendering.
110   //! @return true (turned on) or false depending on the state.
111   Standard_Boolean IsCapping() const
112   {
113     return myIsCapping;
114   }
115
116   //! Get geometrical definition.
117   //! @return geometrical definition of clipping plane
118   const gp_Pln& ToPlane() const { return myPlane; }
119
120   //! Clone plane. Virtual method to simplify copying procedure if plane
121   //! class is redefined at application level to add specific fields to it
122   //! e.g. id, name, etc.
123   //! @return new instance of clipping plane with same properties and attributes.
124   Standard_EXPORT virtual Handle(Graphic3d_ClipPlane) Clone() const;
125
126 public: // @name user-defined graphical attributes
127
128   //! Set material for rendering capping surface.
129   //! @param theMat [in] the material.
130   Standard_EXPORT void SetCappingMaterial (const Graphic3d_MaterialAspect& theMat);
131
132   //! @return capping material.
133   const Graphic3d_MaterialAspect& CappingMaterial() const { return myAspect->FrontMaterial(); }
134
135   //! Set texture to be applied on capping surface.
136   //! @param theTexture [in] the texture.
137   Standard_EXPORT void SetCappingTexture (const Handle(Graphic3d_TextureMap)& theTexture);
138
139   //! @return capping texture map.
140   const Handle(Graphic3d_TextureMap)& CappingTexture() const { return myAspect->TextureMap(); }
141
142   //! Set hatch style (stipple) and turn hatching on.
143   //! @param theStyle [in] the hatch style.
144   Standard_EXPORT void SetCappingHatch (const Aspect_HatchStyle theStyle);
145
146   //! @return hatching style.
147   Aspect_HatchStyle CappingHatch() const { return (Aspect_HatchStyle)myAspect->HatchStyle()->HatchType(); }
148
149   //! Set custom hatch style (stipple) and turn hatching on.
150   //! @param theStyle [in] the hatch pattern.
151   Standard_EXPORT void SetCappingCustomHatch (const Handle(Graphic3d_HatchStyle)& theStyle);
152
153   //! @return hatching style.
154   const Handle(Graphic3d_HatchStyle)& CappingCustomHatch() const { return myAspect->HatchStyle(); }
155
156   //! Turn on hatching.
157   Standard_EXPORT void SetCappingHatchOn();
158
159   //! Turn off hatching.
160   Standard_EXPORT void SetCappingHatchOff();
161
162   //! @return True if hatching mask is turned on.
163   Standard_Boolean IsHatchOn() const { return myAspect->InteriorStyle() == Aspect_IS_HATCH; }
164
165   //! This ID is used for managing associated resources in graphical driver.
166   //! The clip plane can be assigned within a range of IO which can be
167   //! displayed in separate OpenGl contexts. For each of the context an associated
168   //! OpenGl resource for graphical aspects should be created and kept.
169   //! The resources are stored in graphical driver for each of individual groups
170   //! of shared context under the clip plane identifier.
171   //! @return clip plane resource identifier string.
172   const TCollection_AsciiString& GetId() const
173   {
174     return myId;
175   }
176
177 public:
178
179   //! Return capping aspect.
180   //! @return capping surface rendering aspect.
181   const Handle(Graphic3d_AspectFillArea3d)& CappingAspect() const { return myAspect; }
182
183   //! Assign capping aspect.
184   Standard_EXPORT void SetCappingAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect);
185
186   //! Flag indicating whether material for capping plane should be taken from object.
187   //! Default value: FALSE (use dedicated capping plane material).
188   bool ToUseObjectMaterial() const { return (myFlags & Graphic3d_CappingFlags_ObjectMaterial) != 0; }
189
190   //! Set flag for controlling the source of capping plane material.
191   void SetUseObjectMaterial (bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectMaterial); }
192
193   //! Flag indicating whether texture for capping plane should be taken from object.
194   //! Default value: FALSE.
195   bool ToUseObjectTexture() const { return (myFlags & Graphic3d_CappingFlags_ObjectTexture) != 0; }
196
197   //! Set flag for controlling the source of capping plane texture.
198   void SetUseObjectTexture (bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectTexture); }
199
200   //! Flag indicating whether shader program for capping plane should be taken from object.
201   //! Default value: FALSE.
202   bool ToUseObjectShader() const { return (myFlags & Graphic3d_CappingFlags_ObjectShader) != 0; }
203
204   //! Set flag for controlling the source of capping plane shader program.
205   void SetUseObjectShader(bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectShader); }
206
207   //! Return true if some fill area aspect properties should be taken from object.
208   bool ToUseObjectProperties() const { return myFlags != Graphic3d_CappingFlags_None; }
209
210 public: // @name modification counters
211
212   //! @return modification counter for equation.
213   unsigned int MCountEquation() const
214   {
215     return myEquationMod;
216   }
217
218   //! @return modification counter for aspect.
219   unsigned int MCountAspect() const
220   {
221     return myAspectMod;
222   }
223
224 private:
225
226   //! Generate unique object id for OpenGL graphic resource manager.
227   void makeId();
228
229   //! Set capping flag.
230   Standard_EXPORT void setCappingFlag (bool theToUse, int theFlag);
231
232 private:
233
234   Handle(Graphic3d_AspectFillArea3d) myAspect;    //!< fill area aspect
235   TCollection_AsciiString myId;                   //!< resource id
236   gp_Pln                  myPlane;                //!< plane definition
237   Equation                myEquation;             //!< plane equation vector
238   unsigned int            myFlags;                //!< capping flags
239   unsigned int            myEquationMod;          //!< modification counter for equation
240   unsigned int            myAspectMod;            //!< modification counter of aspect
241   Standard_Boolean        myIsOn;                 //!< state of the clipping plane
242   Standard_Boolean        myIsCapping;            //!< state of graphic driver capping
243
244 public:
245
246   DEFINE_STANDARD_RTTIEXT(Graphic3d_ClipPlane,Standard_Transient)
247 };
248
249 DEFINE_STANDARD_HANDLE (Graphic3d_ClipPlane, Standard_Transient)
250
251 #endif