0024070: OpenGL capped object-level clipping planes
[occt.git] / src / Graphic3d / Graphic3d_ClipPlane.hxx
1 // Created on: 2013-07-12
2 // Created by: Anton POLETAEV
3 // Copyright (c) 2013 OPEN CASCADE SAS
4 //
5 // The content of this file is subject to the Open CASCADE Technology Public
6 // License Version 65 (the "License") You may not use the content of this file
7 // except in compliance with the License Please obtain a copy of the License
8 // at http://www.opencascade.org and read it completely before using this file
9 //
10 // The Initial Developer of the Original Code is Open CASCADE SAS, having its
11 // main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France
12 //
13 // The Original Code and all software distributed under the License is
14 // distributed on an "AS IS" basis, without warranty of any kind, and the
15 // Initial Developer hereby disclaims all such warranties, including without
16 // limitation, any warranties of merchantability, fitness for a particular
17 // purpose or non-infringement Please see the License for the specific terms
18 // and conditions governing the rights and limitations under the License
19
20 #ifndef _Graphic3d_ClipPlane_HeaderFile
21 #define _Graphic3d_ClipPlane_HeaderFile
22
23 #include <Standard_Macro.hxx>
24 #include <Standard_TypeDef.hxx>
25 #include <Standard_Transient.hxx>
26 #include <NCollection_Vec4.hxx>
27 #include <Graphic3d_MaterialAspect.hxx>
28 #include <Graphic3d_TextureMap.hxx>
29 #include <Aspect_HatchStyle.hxx>
30
31 DEFINE_STANDARD_HANDLE (Graphic3d_ClipPlane, Standard_Transient)
32
33 class gp_Pln;
34 class Graphic3d_AspectFillArea3d;
35 class Handle(Graphic3d_AspectFillArea3d);
36
37 //! Container for properties describing graphic driver clipping planes.
38 //! It is up to application to create instances of this class and specify its
39 //! properties. The instances are passed into graphic driver or other facilities
40 //! that implement clipping features (e.g. selection).
41 //! Depending on usage context the class can be used to specify:
42 //! - Global clipping applied over the whole scene.
43 //! - Object-level clipping applied for each particular object.
44 //! Please note that the set of planes can define convex clipping volume.
45 //! Be aware that number of clip planes supported by OpenGl is implementation
46 //! dependant: at least 6 planes are available. Thus, take into account
47 //! number of clipping planes passed for rendering: the object planes plus
48 //! the view defined ones.
49 class Graphic3d_ClipPlane : public Standard_Transient
50 {
51 public:
52
53   typedef NCollection_Vec4<Standard_Real> Equation;
54
55   //! Default constructor.
56   //! Initializes clip plane container with the following properties:
57   //! - Equation (0.0, 0.0, 1.0, 0)
58   //! - IsOn (True),
59   //! - IsCapping (False),
60   //! - Material (Graphic3d_NOM_DEFAULT),
61   //! - Texture (NULL),
62   //! - HatchStyle (Aspect_HS_HORIZONTAL),
63   //! - IsHatchOn (False)
64   Standard_EXPORT Graphic3d_ClipPlane();
65
66   //! Copy constructor.
67   //! @param theOther [in] the copied plane.
68   Standard_EXPORT Graphic3d_ClipPlane(const Graphic3d_ClipPlane& theOther);
69
70   //! Construct clip plane for the passed equation.
71   //! By default the plane is on, capping is turned off.
72   //! @param theEquation [in] the plane equation.
73   Standard_EXPORT Graphic3d_ClipPlane (const Equation& theEquation);
74
75   //! Construct clip plane from the passed geomertical definition.
76   //! By default the plane is on, capping is turned off.
77   //! @param thePlane [in] the plane.
78   Standard_EXPORT Graphic3d_ClipPlane (const gp_Pln& thePlane);
79
80   //! Set plane equation by its geometrical definition.
81   //! @param thePlane [in] the plane.
82   Standard_EXPORT void SetEquation (const gp_Pln& thePlane);
83
84   //! Set 4-component equation vector for clipping plane.
85   //! @param theEquation [in] the XYZW (or "ABCD") equation vector.
86   Standard_EXPORT void SetEquation (const Equation& theEquation);
87
88   //! Get 4-component equation vector for clipping plane.
89   //! @return clipping plane equation vector.
90   const Equation& GetEquation() const
91   {
92     return myEquation;
93   }
94
95   //! Check that the clipping plane is turned on.
96   //! @return boolean flag indicating whether the plane is in on or off state.
97   Standard_Boolean IsOn() const
98   {
99     return myIsOn;
100   }
101
102   //! Change state of the clipping plane.
103   //! @param theIsOn [in] the flag specifying whether the graphic driver
104   //! clipping by this plane should be turned on or off.
105   Standard_EXPORT void SetOn(const Standard_Boolean theIsOn);
106
107   //! Change state of capping surface rendering.
108   //! @param theIsOn [in] the flag specifying whether the graphic driver should
109   //! perform rendering of capping surface produced by this plane. The graphic
110   //! driver produces this surface for convex graphics by means of stencil-test
111   //! and multipass rendering.
112   Standard_EXPORT void SetCapping(const Standard_Boolean theIsOn);
113
114   //! Check state of capping surface rendering.
115   //! @return true (turned on) or false depending on the state.
116   Standard_Boolean IsCapping() const
117   {
118     return myIsCapping;
119   }
120
121   //! Get geomertical definition. The plane is built up
122   //! from the equation clipping plane equation vector.
123   //! @return geometrical definition of clipping plane.
124   Standard_EXPORT gp_Pln ToPlane() const;
125
126   //! Clone plane. Virtual method to simplify copying procedure if plane
127   //! class is redefined at application level to add specific fields to it
128   //! e.g. id, name, etc.
129   //! @return new instance of clipping plane with same properties and attributes.
130   Standard_EXPORT virtual Handle(Graphic3d_ClipPlane) Clone() const;
131
132 public: // @name user-defined graphical attributes
133
134   //! Set material for rendering capping surface.
135   //! @param theMat [in] the material.
136   Standard_EXPORT void SetCappingMaterial (const Graphic3d_MaterialAspect& theMat);
137
138   //! @return capping material.
139   const Graphic3d_MaterialAspect& CappingMaterial() const
140   {
141     return myMaterial;
142   }
143
144   //! Set texture to be applied on capping surface.
145   //! @param theTexture [in] the texture.
146   Standard_EXPORT void SetCappingTexture (const Handle(Graphic3d_TextureMap)& theTexture);
147
148   //! @return capping texture map.
149   const Handle(Graphic3d_TextureMap)& CappingTexture() const
150   {
151     return myTexture;
152   }
153
154   //! Set hatch style (stipple) and turn hatching on.
155   //! @param theStyle [in] the hatch style.
156   Standard_EXPORT void SetCappingHatch (const Aspect_HatchStyle theStyle);
157
158   //! @return hatching style.
159   Aspect_HatchStyle CappingHatch() const
160   {
161     return myHatch;
162   }
163
164   //! Turn on hatching.
165   Standard_EXPORT void SetCappingHatchOn();
166
167   //! Turn off hatching.
168   Standard_EXPORT void SetCappingHatchOff();
169
170   //! @return True if hatching mask is turned on.
171   Standard_Boolean IsHatchOn() const
172   {
173     return myHatchOn;
174   }
175
176   //! This ID is used for managing associated resources in graphical driver.
177   //! The clip plane can be assigned within a range of IO which can be
178   //! displayed in separate OpenGl contexts. For each of the context an associated
179   //! OpenGl resource for graphical aspects should be created and kept.
180   //! The resources are stored in graphical driver for each of individual groups
181   //! of shared context under the clip plane identifier.
182   //! @return clip plane resource identifier string.
183   const TCollection_AsciiString& GetId() const
184   {
185     return myId;
186   }
187
188   //! Compute and return capping apsect from the graphical attributes.
189   //! @return capping surface rendering aspect.
190   Standard_EXPORT Handle(Graphic3d_AspectFillArea3d) CappingAspect() const;
191
192 public: // @name modificaton counters
193
194   //! @return modification counter for equation.
195   unsigned int MCountEquation() const
196   {
197     return myEquationMod;
198   }
199
200   //! @return modification counter for aspect.
201   unsigned int MCountAspect() const
202   {
203     return myAspectMod;
204   }
205
206 private:
207
208   void MakeId();
209
210 private:
211
212   Equation                     myEquation;    //!< Plane equation vector.
213   Standard_Boolean             myIsOn;        //!< State of the clipping plane.
214   Standard_Boolean             myIsCapping;   //!< State of graphic driver capping.
215   Graphic3d_MaterialAspect     myMaterial;    //!< Capping surface material.
216   Handle(Graphic3d_TextureMap) myTexture;     //!< Capping surface texture.
217   Aspect_HatchStyle            myHatch;       //!< Capping surface hatch mask.
218   Standard_Boolean             myHatchOn;     //!< Capping surface hatching flag.
219   TCollection_AsciiString      myId;          //!< Resource id.
220   unsigned int                 myEquationMod; //!< Modification counter for equation.
221   unsigned int                 myAspectMod;   //!< Modification counter of aspect.
222
223 public:
224
225   DEFINE_STANDARD_RTTI(Graphic3d_ClipPlane);
226 };
227
228 #endif