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 <Aspect_HatchStyle.hxx>
21 #include <Graphic3d_AspectFillArea3d.hxx>
22 #include <Graphic3d_BndBox3d.hxx>
23 #include <Graphic3d_CappingFlags.hxx>
24 #include <Graphic3d_TextureMap.hxx>
25 #include <NCollection_Vec4.hxx>
26 #include <Standard_Macro.hxx>
27 #include <Standard_TypeDef.hxx>
28 #include <Standard_Transient.hxx>
31 enum Graphic3d_ClipState
33 Graphic3d_ClipState_Out, //!< fully outside (clipped) - should be discarded
34 Graphic3d_ClipState_In, //!< fully inside (NOT clipped) - should NOT be discarded
35 Graphic3d_ClipState_On, //!< on (not clipped / partially clipped) - should NOT be discarded
38 //! Container for properties describing either a Clipping halfspace (single Clipping Plane),
39 //! or a chain of Clipping Planes defining logical AND (conjunction) operation.
40 //! The plane equation is specified in "world" coordinate system.
41 class Graphic3d_ClipPlane : public Standard_Transient
43 DEFINE_STANDARD_RTTIEXT(Graphic3d_ClipPlane,Standard_Transient)
46 //! Type defining XYZW (ABCD) plane equation - left for compatibility with old code using Graphic3d_ClipPlane::Equation type.
47 typedef Graphic3d_Vec4d 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 Graphic3d_Vec4d& 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 Graphic3d_Vec4d& theEquation);
86 //! Get 4-component equation vector for clipping plane.
87 //! @return clipping plane equation vector.
88 const Graphic3d_Vec4d& GetEquation() const { return myEquation; }
90 //! Get 4-component equation vector for clipping plane.
91 //! @return clipping plane equation vector.
92 const Graphic3d_Vec4d& ReversedEquation() const { return myEquationRev; }
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
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);
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);
113 //! Check state of capping surface rendering.
114 //! @return true (turned on) or false depending on the state.
115 Standard_Boolean IsCapping() const
120 //! Get geometrical definition.
121 //! @return geometrical definition of clipping plane
122 const gp_Pln& ToPlane() const { return myPlane; }
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;
132 //! Return TRUE if this item defines a conjunction (logical AND) between a set of Planes.
133 //! Graphic3d_ClipPlane item defines either a Clipping halfspace (single Clipping Plane)
134 //! or a Clipping volume defined by a logical AND (conjunction) operation between a set of Planes defined as a Chain
135 //! (so that the volume cuts a space only in case if check fails for ALL Planes in the Chain).
137 //! Note that Graphic3d_ClipPlane item cannot:
138 //! - Define a Chain with logical OR (disjunction) operation;
139 //! this should be done through Graphic3d_SequenceOfHClipPlane.
140 //! - Define nested Chains.
141 //! - Disable Chain items; only entire Chain can be disabled (by disabled a head of Chain).
143 //! The head of a Chain defines all visual properties of the Chain,
144 //! so that Graphic3d_ClipPlane of next items in a Chain merely defines only geometrical definition of the plane.
145 Standard_Boolean IsChain() const { return !myNextInChain.IsNull(); }
147 //! Return the previous plane in a Chain of Planes defining logical AND operation,
148 //! or NULL if there is no Chain or it is a first element in Chain.
149 //! When clipping is defined by a Chain of Planes,
150 //! it cuts a space only in case if check fails for all Planes in Chain.
151 Handle(Graphic3d_ClipPlane) ChainPreviousPlane() const { return myPrevInChain; }
153 //! Return the next plane in a Chain of Planes defining logical AND operation,
154 //! or NULL if there is no chain or it is a last element in chain.
156 const Handle(Graphic3d_ClipPlane)& ChainNextPlane() const { return myNextInChain; }
158 //! Return the number of chains in forward direction (including this item, so it is always >= 1).
159 //! For a head of Chain - returns the length of entire Chain.
160 Standard_Integer NbChainNextPlanes() const { return myChainLenFwd; }
162 //! Set the next plane in a Chain of Planes.
163 //! This operation also updates relationship between chains (Previous/Next items),
164 //! so that the previously set Next plane is cut off.
165 Standard_EXPORT void SetChainNextPlane (const Handle(Graphic3d_ClipPlane)& thePlane);
167 public: // @name user-defined graphical attributes
169 //! Set material for rendering capping surface.
170 //! @param theMat [in] the material.
171 Standard_EXPORT void SetCappingMaterial (const Graphic3d_MaterialAspect& theMat);
173 //! @return capping material.
174 const Graphic3d_MaterialAspect& CappingMaterial() const { return myAspect->FrontMaterial(); }
176 //! Set texture to be applied on capping surface.
177 //! @param theTexture [in] the texture.
178 Standard_EXPORT void SetCappingTexture (const Handle(Graphic3d_TextureMap)& theTexture);
180 //! @return capping texture map.
181 Handle(Graphic3d_TextureMap) CappingTexture() const { return !myAspect->TextureSet().IsNull() && !myAspect->TextureSet()->IsEmpty()
182 ? myAspect->TextureSet()->First()
183 : Handle(Graphic3d_TextureMap)(); }
185 //! Set hatch style (stipple) and turn hatching on.
186 //! @param theStyle [in] the hatch style.
187 Standard_EXPORT void SetCappingHatch (const Aspect_HatchStyle theStyle);
189 //! @return hatching style.
190 Aspect_HatchStyle CappingHatch() const { return (Aspect_HatchStyle)myAspect->HatchStyle()->HatchType(); }
192 //! Set custom hatch style (stipple) and turn hatching on.
193 //! @param theStyle [in] the hatch pattern.
194 Standard_EXPORT void SetCappingCustomHatch (const Handle(Graphic3d_HatchStyle)& theStyle);
196 //! @return hatching style.
197 const Handle(Graphic3d_HatchStyle)& CappingCustomHatch() const { return myAspect->HatchStyle(); }
199 //! Turn on hatching.
200 Standard_EXPORT void SetCappingHatchOn();
202 //! Turn off hatching.
203 Standard_EXPORT void SetCappingHatchOff();
205 //! @return True if hatching mask is turned on.
206 Standard_Boolean IsHatchOn() const { return myAspect->InteriorStyle() == Aspect_IS_HATCH; }
208 //! This ID is used for managing associated resources in graphical driver.
209 //! The clip plane can be assigned within a range of IO which can be
210 //! displayed in separate OpenGl contexts. For each of the context an associated
211 //! OpenGl resource for graphical aspects should be created and kept.
212 //! The resources are stored in graphical driver for each of individual groups
213 //! of shared context under the clip plane identifier.
214 //! @return clip plane resource identifier string.
215 const TCollection_AsciiString& GetId() const
222 //! Return capping aspect.
223 //! @return capping surface rendering aspect.
224 const Handle(Graphic3d_AspectFillArea3d)& CappingAspect() const { return myAspect; }
226 //! Assign capping aspect.
227 Standard_EXPORT void SetCappingAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect);
229 //! Flag indicating whether material for capping plane should be taken from object.
230 //! Default value: FALSE (use dedicated capping plane material).
231 bool ToUseObjectMaterial() const { return (myFlags & Graphic3d_CappingFlags_ObjectMaterial) != 0; }
233 //! Set flag for controlling the source of capping plane material.
234 void SetUseObjectMaterial (bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectMaterial); }
236 //! Flag indicating whether texture for capping plane should be taken from object.
237 //! Default value: FALSE.
238 bool ToUseObjectTexture() const { return (myFlags & Graphic3d_CappingFlags_ObjectTexture) != 0; }
240 //! Set flag for controlling the source of capping plane texture.
241 void SetUseObjectTexture (bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectTexture); }
243 //! Flag indicating whether shader program for capping plane should be taken from object.
244 //! Default value: FALSE.
245 bool ToUseObjectShader() const { return (myFlags & Graphic3d_CappingFlags_ObjectShader) != 0; }
247 //! Set flag for controlling the source of capping plane shader program.
248 void SetUseObjectShader(bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectShader); }
250 //! Return true if some fill area aspect properties should be taken from object.
251 bool ToUseObjectProperties() const { return myFlags != Graphic3d_CappingFlags_None; }
255 //! Check if the given point is outside / inside / on section.
256 Graphic3d_ClipState ProbePoint (const Graphic3d_Vec4d& thePoint) const
258 Graphic3d_ClipState aState = Graphic3d_ClipState_Out;
259 for (const Graphic3d_ClipPlane* aPlaneIter = this; aPlaneIter != NULL; aPlaneIter = aPlaneIter->myNextInChain.get())
261 Graphic3d_ClipState aPlnState = aPlaneIter->ProbePointHalfspace (thePoint);
262 if (aPlnState == Graphic3d_ClipState_In)
264 return Graphic3d_ClipState_In;
266 else if (aPlnState != Graphic3d_ClipState_Out)
268 aState = Graphic3d_ClipState_On;
274 //! Check if the given bounding box is fully outside / fully inside.
275 Graphic3d_ClipState ProbeBox (const Graphic3d_BndBox3d& theBox) const
277 Graphic3d_ClipState aState = Graphic3d_ClipState_Out;
278 for (const Graphic3d_ClipPlane* aPlaneIter = this; aPlaneIter != NULL; aPlaneIter = aPlaneIter->myNextInChain.get())
280 if (aPlaneIter->IsBoxFullInHalfspace (theBox))
282 // within union operation, if box is entirely inside at least one half-space, others can be ignored
283 return Graphic3d_ClipState_In;
285 else if (!aPlaneIter->IsBoxFullOutHalfspace (theBox))
287 // if at least one full out test fail, clipping state is inconclusive (partially clipped)
288 aState = Graphic3d_ClipState_On;
296 //! Check if the given point is outside of the half-space (e.g. should be discarded by clipping plane).
297 Graphic3d_ClipState ProbePointHalfspace (const Graphic3d_Vec4d& thePoint) const
299 const Standard_Real aVal = myEquation.Dot (thePoint);
301 ? Graphic3d_ClipState_Out
303 ? Graphic3d_ClipState_On
304 : Graphic3d_ClipState_In);
307 //! Check if the given bounding box is fully outside / fully inside the half-space.
308 Graphic3d_ClipState ProbeBoxHalfspace (const Graphic3d_BndBox3d& theBox) const
310 if (IsBoxFullOutHalfspace (theBox))
312 return Graphic3d_ClipState_Out;
314 return IsBoxFullInHalfspace (theBox)
315 ? Graphic3d_ClipState_In
316 : Graphic3d_ClipState_On;
319 //! Check if the given point is outside of the half-space (e.g. should be discarded by clipping plane).
320 bool IsPointOutHalfspace (const Graphic3d_Vec4d& thePoint) const { return ProbePointHalfspace (thePoint) == Graphic3d_ClipState_Out; }
322 //! Check if the given bounding box is fully outside of the half-space (e.g. should be discarded by clipping plane).
323 bool IsBoxFullOutHalfspace (const Graphic3d_BndBox3d& theBox) const
325 const Graphic3d_Vec4d aMaxPnt (myEquation.x() > 0.0 ? theBox.CornerMax().x() : theBox.CornerMin().x(),
326 myEquation.y() > 0.0 ? theBox.CornerMax().y() : theBox.CornerMin().y(),
327 myEquation.z() > 0.0 ? theBox.CornerMax().z() : theBox.CornerMin().z(),
329 return IsPointOutHalfspace (aMaxPnt);
332 //! Check if the given bounding box is fully inside (or touches from inside) the half-space (e.g. NOT discarded by clipping plane).
333 bool IsBoxFullInHalfspace (const Graphic3d_BndBox3d& theBox) const
335 const Graphic3d_Vec4d aMinPnt (myEquation.x() > 0.0 ? theBox.CornerMin().x() : theBox.CornerMax().x(),
336 myEquation.y() > 0.0 ? theBox.CornerMin().y() : theBox.CornerMax().y(),
337 myEquation.z() > 0.0 ? theBox.CornerMin().z() : theBox.CornerMax().z(),
339 return !IsPointOutHalfspace (aMinPnt);
342 public: // @name modification counters
344 //! @return modification counter for equation.
345 unsigned int MCountEquation() const
347 return myEquationMod;
350 //! @return modification counter for aspect.
351 unsigned int MCountAspect() const
358 //! Generate unique object id for OpenGL graphic resource manager.
361 //! Set capping flag.
362 Standard_EXPORT void setCappingFlag (bool theToUse, int theFlag);
364 //! Update chain length in backward direction.
365 void updateChainLen();
367 //! Update inversed plane definition from main plane.
368 void updateInversedPlane()
370 gp_Pln aPlane = myPlane;
371 aPlane.SetAxis (aPlane.Axis().Reversed());
372 aPlane.Coefficients (myEquationRev[0], myEquationRev[1], myEquationRev[2], myEquationRev[3]);
377 Handle(Graphic3d_AspectFillArea3d) myAspect; //!< fill area aspect
378 Handle(Graphic3d_ClipPlane) myNextInChain; //!< next plane in a chain of planes defining logical AND operation
379 Graphic3d_ClipPlane* myPrevInChain; //!< previous plane in a chain of planes defining logical AND operation
380 TCollection_AsciiString myId; //!< resource id
381 gp_Pln myPlane; //!< plane definition
382 Graphic3d_Vec4d myEquation; //!< plane equation vector
383 Graphic3d_Vec4d myEquationRev; //!< reversed plane equation
384 Standard_Integer myChainLenFwd; //!< chain length in forward direction (including this item)
385 unsigned int myFlags; //!< capping flags
386 unsigned int myEquationMod; //!< modification counter for equation
387 unsigned int myAspectMod; //!< modification counter of aspect
388 Standard_Boolean myIsOn; //!< state of the clipping plane
389 Standard_Boolean myIsCapping; //!< state of graphic driver capping
393 DEFINE_STANDARD_HANDLE (Graphic3d_ClipPlane, Standard_Transient)