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