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   Handle(Graphic3d_TextureMap) CappingTexture() const { return !myAspect->TextureSet().IsNull() && !myAspect->TextureSet()->IsEmpty()
 141                                                               ? myAspect->TextureSet()->First()
 142                                                               : Handle(Graphic3d_TextureMap)(); }
 143
 144   //! Set hatch style (stipple) and turn hatching on.
 145   //! @param theStyle [in] the hatch style.
 146   Standard_EXPORT void SetCappingHatch (const Aspect_HatchStyle theStyle);
 147
 148   //! @return hatching style.
 149   Aspect_HatchStyle CappingHatch() const { return (Aspect_HatchStyle)myAspect->HatchStyle()->HatchType(); }
 150
 151   //! Set custom hatch style (stipple) and turn hatching on.
 152   //! @param theStyle [in] the hatch pattern.
 153   Standard_EXPORT void SetCappingCustomHatch (const Handle(Graphic3d_HatchStyle)& theStyle);
 154
 155   //! @return hatching style.
 156   const Handle(Graphic3d_HatchStyle)& CappingCustomHatch() const { return myAspect->HatchStyle(); }
 157
 158   //! Turn on hatching.
 159   Standard_EXPORT void SetCappingHatchOn();
 160
 161   //! Turn off hatching.
 162   Standard_EXPORT void SetCappingHatchOff();
 163
 164   //! @return True if hatching mask is turned on.
 165   Standard_Boolean IsHatchOn() const { return myAspect->InteriorStyle() == Aspect_IS_HATCH; }
 166
 167   //! This ID is used for managing associated resources in graphical driver.
 168   //! The clip plane can be assigned within a range of IO which can be
 169   //! displayed in separate OpenGl contexts. For each of the context an associated
 170   //! OpenGl resource for graphical aspects should be created and kept.
 171   //! The resources are stored in graphical driver for each of individual groups
 172   //! of shared context under the clip plane identifier.
 173   //! @return clip plane resource identifier string.
 174   const TCollection_AsciiString& GetId() const
 175   {
 176     return myId;
 177   }
 178
 179 public:
 180
 181   //! Return capping aspect.
 182   //! @return capping surface rendering aspect.
 183   const Handle(Graphic3d_AspectFillArea3d)& CappingAspect() const { return myAspect; }
 184
 185   //! Assign capping aspect.
 186   Standard_EXPORT void SetCappingAspect (const Handle(Graphic3d_AspectFillArea3d)& theAspect);
 187
 188   //! Flag indicating whether material for capping plane should be taken from object.
 189   //! Default value: FALSE (use dedicated capping plane material).
 190   bool ToUseObjectMaterial() const { return (myFlags & Graphic3d_CappingFlags_ObjectMaterial) != 0; }
 191
 192   //! Set flag for controlling the source of capping plane material.
 193   void SetUseObjectMaterial (bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectMaterial); }
 194
 195   //! Flag indicating whether texture for capping plane should be taken from object.
 196   //! Default value: FALSE.
 197   bool ToUseObjectTexture() const { return (myFlags & Graphic3d_CappingFlags_ObjectTexture) != 0; }
 198
 199   //! Set flag for controlling the source of capping plane texture.
 200   void SetUseObjectTexture (bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectTexture); }
 201
 202   //! Flag indicating whether shader program for capping plane should be taken from object.
 203   //! Default value: FALSE.
 204   bool ToUseObjectShader() const { return (myFlags & Graphic3d_CappingFlags_ObjectShader) != 0; }
 205
 206   //! Set flag for controlling the source of capping plane shader program.
 207   void SetUseObjectShader(bool theToUse) { setCappingFlag (theToUse, Graphic3d_CappingFlags_ObjectShader); }
 208
 209   //! Return true if some fill area aspect properties should be taken from object.
 210   bool ToUseObjectProperties() const { return myFlags != Graphic3d_CappingFlags_None; }
 211
 212 public: // @name modification counters
 213
 214   //! @return modification counter for equation.
 215   unsigned int MCountEquation() const
 216   {
 217     return myEquationMod;
 218   }
 219
 220   //! @return modification counter for aspect.
 221   unsigned int MCountAspect() const
 222   {
 223     return myAspectMod;
 224   }
 225
 226 private:
 227
 228   //! Generate unique object id for OpenGL graphic resource manager.
 229   void makeId();
 230
 231   //! Set capping flag.
 232   Standard_EXPORT void setCappingFlag (bool theToUse, int theFlag);
 233
 234 private:
 235
 236   Handle(Graphic3d_AspectFillArea3d) myAspect;    //!< fill area aspect
 237   TCollection_AsciiString myId;                   //!< resource id
 238   gp_Pln                  myPlane;                //!< plane definition
 239   Equation                myEquation;             //!< plane equation vector
 240   unsigned int            myFlags;                //!< capping flags
 241   unsigned int            myEquationMod;          //!< modification counter for equation
 242   unsigned int            myAspectMod;            //!< modification counter of aspect
 243   Standard_Boolean        myIsOn;                 //!< state of the clipping plane
 244   Standard_Boolean        myIsCapping;            //!< state of graphic driver capping
 245
 246 public:
 247
 248   DEFINE_STANDARD_RTTIEXT(Graphic3d_ClipPlane,Standard_Transient)
 249 };
 250
 251 DEFINE_STANDARD_HANDLE (Graphic3d_ClipPlane, Standard_Transient)
 252
 253 #endif