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 class gp_Pln;
  28 class Graphic3d_AspectFillArea3d;
  29 class Handle(Graphic3d_AspectFillArea3d);
  30 class Handle(Graphic3d_ClipPlane);
  31
  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
  46 {
  47 public:
  48
  49   typedef NCollection_Vec4<Standard_Real> Equation;
  50
  51   //! Default constructor.
  52   //! Initializes clip plane container with the following properties:
  53   //! - Equation (0.0, 0.0, 1.0, 0)
  54   //! - IsOn (True),
  55   //! - IsCapping (False),
  56   //! - Material (Graphic3d_NOM_DEFAULT),
  57   //! - Texture (NULL),
  58   //! - HatchStyle (Aspect_HS_HORIZONTAL),
  59   //! - IsHatchOn (False)
  60   Standard_EXPORT Graphic3d_ClipPlane();
  61
  62   //! Copy constructor.
  63   //! @param theOther [in] the copied plane.
  64   Standard_EXPORT Graphic3d_ClipPlane(const Graphic3d_ClipPlane& theOther);
  65
  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);
  70
  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);
  75
  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);
  80
  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);
  85
  86   //! Get 4-component equation vector for clipping plane.
  87   //! @return clipping plane equation vector.
  88   const Equation& GetEquation() const
  89   {
  90     return myEquation;
  91   }
  92
  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
  96   {
  97     return myIsOn;
  98   }
  99
 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);
 104
 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);
 111
 112   //! Check state of capping surface rendering.
 113   //! @return true (turned on) or false depending on the state.
 114   Standard_Boolean IsCapping() const
 115   {
 116     return myIsCapping;
 117   }
 118
 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;
 123
 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;
 129
 130 public: // @name user-defined graphical attributes
 131
 132   //! Set material for rendering capping surface.
 133   //! @param theMat [in] the material.
 134   Standard_EXPORT void SetCappingMaterial (const Graphic3d_MaterialAspect& theMat);
 135
 136   //! @return capping material.
 137   const Graphic3d_MaterialAspect& CappingMaterial() const
 138   {
 139     return myMaterial;
 140   }
 141
 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);
 145
 146   //! @return capping texture map.
 147   const Handle(Graphic3d_TextureMap)& CappingTexture() const
 148   {
 149     return myTexture;
 150   }
 151
 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);
 155
 156   //! @return hatching style.
 157   Aspect_HatchStyle CappingHatch() const
 158   {
 159     return myHatch;
 160   }
 161
 162   //! Turn on hatching.
 163   Standard_EXPORT void SetCappingHatchOn();
 164
 165   //! Turn off hatching.
 166   Standard_EXPORT void SetCappingHatchOff();
 167
 168   //! @return True if hatching mask is turned on.
 169   Standard_Boolean IsHatchOn() const
 170   {
 171     return myHatchOn;
 172   }
 173
 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
 182   {
 183     return myId;
 184   }
 185
 186   //! Compute and return capping aspect from the graphical attributes.
 187   //! @return capping surface rendering aspect.
 188   Standard_EXPORT Handle(Graphic3d_AspectFillArea3d) CappingAspect() const;
 189
 190 public: // @name modification counters
 191
 192   //! @return modification counter for equation.
 193   unsigned int MCountEquation() const
 194   {
 195     return myEquationMod;
 196   }
 197
 198   //! @return modification counter for aspect.
 199   unsigned int MCountAspect() const
 200   {
 201     return myAspectMod;
 202   }
 203
 204 private:
 205
 206   void MakeId();
 207
 208 private:
 209
 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.
 220
 221 public:
 222
 223   DEFINE_STANDARD_RTTI(Graphic3d_ClipPlane);
 224 };
 225
 226 DEFINE_STANDARD_HANDLE (Graphic3d_ClipPlane, Standard_Transient)
 227
 228 #endif