1 // Created on: 2013-07-12
2 // Created by: Anton POLETAEV
3 // Copyright (c) 2013-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
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.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _Graphic3d_ClipPlane_HeaderFile
17 #define _Graphic3d_ClipPlane_HeaderFile
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>
28 class Graphic3d_AspectFillArea3d;
29 class Handle(Graphic3d_AspectFillArea3d);
30 class Handle(Graphic3d_ClipPlane);
32 //! Container for properties describing graphic driver clipping planes.
33 //! It is up to application to create instances of this class and specify its
34 //! properties. The instances are passed into graphic driver or other facilities
35 //! that implement clipping features (e.g. selection).
36 //! Depending on usage context the class can be used to specify:
37 //! - Global clipping applied over the whole scene.
38 //! - Object-level clipping applied for each particular object.
39 //! The plane equation is specified in "world" coordinate system.
40 //! Please note that the set of planes can define convex clipping volume.
41 //! Be aware that number of clip planes supported by OpenGl is implementation
42 //! dependent: at least 6 planes are available. Thus, take into account
43 //! number of clipping planes passed for rendering: the object planes plus
44 //! the view defined ones.
45 class Graphic3d_ClipPlane : public Standard_Transient
49 typedef NCollection_Vec4<Standard_Real> Equation;
51 //! Default constructor.
52 //! Initializes clip plane container with the following properties:
53 //! - Equation (0.0, 0.0, 1.0, 0)
55 //! - IsCapping (False),
56 //! - Material (Graphic3d_NOM_DEFAULT),
58 //! - HatchStyle (Aspect_HS_HORIZONTAL),
59 //! - IsHatchOn (False)
60 Standard_EXPORT Graphic3d_ClipPlane();
63 //! @param theOther [in] the copied plane.
64 Standard_EXPORT Graphic3d_ClipPlane(const Graphic3d_ClipPlane& theOther);
66 //! Construct clip plane for the passed equation.
67 //! By default the plane is on, capping is turned off.
68 //! @param theEquation [in] the plane equation.
69 Standard_EXPORT Graphic3d_ClipPlane (const Equation& theEquation);
71 //! Construct clip plane from the passed geometrical definition.
72 //! By default the plane is on, capping is turned off.
73 //! @param thePlane [in] the plane.
74 Standard_EXPORT Graphic3d_ClipPlane (const gp_Pln& thePlane);
76 //! Set plane equation by its geometrical definition.
77 //! The equation is specified in "world" coordinate system.
78 //! @param thePlane [in] the plane.
79 Standard_EXPORT void SetEquation (const gp_Pln& thePlane);
81 //! Set 4-component equation vector for clipping plane.
82 //! The equation is specified in "world" coordinate system.
83 //! @param theEquation [in] the XYZW (or "ABCD") equation vector.
84 Standard_EXPORT void SetEquation (const Equation& theEquation);
86 //! Get 4-component equation vector for clipping plane.
87 //! @return clipping plane equation vector.
88 const Equation& GetEquation() const
93 //! Check that the clipping plane is turned on.
94 //! @return boolean flag indicating whether the plane is in on or off state.
95 Standard_Boolean IsOn() const
100 //! Change state of the clipping plane.
101 //! @param theIsOn [in] the flag specifying whether the graphic driver
102 //! clipping by this plane should be turned on or off.
103 Standard_EXPORT void SetOn(const Standard_Boolean theIsOn);
105 //! Change state of capping surface rendering.
106 //! @param theIsOn [in] the flag specifying whether the graphic driver should
107 //! perform rendering of capping surface produced by this plane. The graphic
108 //! driver produces this surface for convex graphics by means of stencil-test
109 //! and multi-pass rendering.
110 Standard_EXPORT void SetCapping(const Standard_Boolean theIsOn);
112 //! Check state of capping surface rendering.
113 //! @return true (turned on) or false depending on the state.
114 Standard_Boolean IsCapping() const
119 //! Get geometrical definition. The plane is built up
120 //! from the equation clipping plane equation vector.
121 //! @return geometrical definition of clipping plane.
122 Standard_EXPORT gp_Pln ToPlane() const;
124 //! Clone plane. Virtual method to simplify copying procedure if plane
125 //! class is redefined at application level to add specific fields to it
126 //! e.g. id, name, etc.
127 //! @return new instance of clipping plane with same properties and attributes.
128 Standard_EXPORT virtual Handle(Graphic3d_ClipPlane) Clone() const;
130 public: // @name user-defined graphical attributes
132 //! Set material for rendering capping surface.
133 //! @param theMat [in] the material.
134 Standard_EXPORT void SetCappingMaterial (const Graphic3d_MaterialAspect& theMat);
136 //! @return capping material.
137 const Graphic3d_MaterialAspect& CappingMaterial() const
142 //! Set texture to be applied on capping surface.
143 //! @param theTexture [in] the texture.
144 Standard_EXPORT void SetCappingTexture (const Handle(Graphic3d_TextureMap)& theTexture);
146 //! @return capping texture map.
147 const Handle(Graphic3d_TextureMap)& CappingTexture() const
152 //! Set hatch style (stipple) and turn hatching on.
153 //! @param theStyle [in] the hatch style.
154 Standard_EXPORT void SetCappingHatch (const Aspect_HatchStyle theStyle);
156 //! @return hatching style.
157 Aspect_HatchStyle CappingHatch() const
162 //! Turn on hatching.
163 Standard_EXPORT void SetCappingHatchOn();
165 //! Turn off hatching.
166 Standard_EXPORT void SetCappingHatchOff();
168 //! @return True if hatching mask is turned on.
169 Standard_Boolean IsHatchOn() const
174 //! This ID is used for managing associated resources in graphical driver.
175 //! The clip plane can be assigned within a range of IO which can be
176 //! displayed in separate OpenGl contexts. For each of the context an associated
177 //! OpenGl resource for graphical aspects should be created and kept.
178 //! The resources are stored in graphical driver for each of individual groups
179 //! of shared context under the clip plane identifier.
180 //! @return clip plane resource identifier string.
181 const TCollection_AsciiString& GetId() const
186 //! Compute and return capping aspect from the graphical attributes.
187 //! @return capping surface rendering aspect.
188 Standard_EXPORT Handle(Graphic3d_AspectFillArea3d) CappingAspect() const;
190 public: // @name modification counters
192 //! @return modification counter for equation.
193 unsigned int MCountEquation() const
195 return myEquationMod;
198 //! @return modification counter for aspect.
199 unsigned int MCountAspect() const
210 Equation myEquation; //!< Plane equation vector.
211 Standard_Boolean myIsOn; //!< State of the clipping plane.
212 Standard_Boolean myIsCapping; //!< State of graphic driver capping.
213 Graphic3d_MaterialAspect myMaterial; //!< Capping surface material.
214 Handle(Graphic3d_TextureMap) myTexture; //!< Capping surface texture.
215 Aspect_HatchStyle myHatch; //!< Capping surface hatch mask.
216 Standard_Boolean myHatchOn; //!< Capping surface hatching flag.
217 TCollection_AsciiString myId; //!< Resource id.
218 unsigned int myEquationMod; //!< Modification counter for equation.
219 unsigned int myAspectMod; //!< Modification counter of aspect.
223 DEFINE_STANDARD_RTTI(Graphic3d_ClipPlane, Standard_Transient);
226 DEFINE_STANDARD_HANDLE (Graphic3d_ClipPlane, Standard_Transient)