src/OpenGl/OpenGl_FrameBuffer.hxx

   1 // Created by: Kirill GAVRILOV
   2 // Copyright (c) 2011-2014 OPEN CASCADE SAS
   3 //
   4 // This file is part of Open CASCADE Technology software library.
   5 //
   6 // This library is free software; you can redistribute it and/or modify it under
   7 // the terms of the GNU Lesser General Public License version 2.1 as published
   8 // by the Free Software Foundation, with special exception defined in the file
   9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  10 // distribution for complete text of the license and disclaimer of any warranty.
  11 //
  12 // Alternatively, this file may be used under the terms of Open CASCADE
  13 // commercial license or contractual agreement.
  14
  15 #ifndef OPENGL_FRAME_BUFFER_H
  16 #define OPENGL_FRAME_BUFFER_H
  17
  18 #include <OpenGl_Resource.hxx>
  19
  20 #include <Graphic3d_BufferType.hxx>
  21 #include <Graphic3d_Vec2.hxx>
  22 #include <NCollection_Vector.hxx>
  23 #include <NCollection_Sequence.hxx>
  24
  25 class Image_PixMap;
  26 class OpenGl_Texture;
  27
  28 DEFINE_STANDARD_HANDLE(OpenGl_FrameBuffer, OpenGl_Resource)
  29
  30 //! Short declaration of useful collection types.
  31 typedef NCollection_Vector<Standard_Integer> OpenGl_ColorFormats;
  32
  33 //! Class implements FrameBuffer Object (FBO) resource
  34 //! intended for off-screen rendering.
  35 class OpenGl_FrameBuffer : public OpenGl_Resource
  36 {
  37
  38 public:
  39
  40   //! Helpful constants
  41   static const unsigned int NO_FRAMEBUFFER  = 0;
  42   static const unsigned int NO_RENDERBUFFER = 0;
  43
  44 public:
  45
  46   //! Dump content into image.
  47   //! @param theGlCtx      bound OpenGL context
  48   //! @param theFbo        FBO to dump (or window buffer, if NULL)
  49   //! @param theImage      target image
  50   //! @param theBufferType buffer type (attachment) to dump
  51   //! @return TRUE on success
  52   Standard_EXPORT static Standard_Boolean BufferDump (const Handle(OpenGl_Context)& theGlCtx,
  53                                                       const Handle(OpenGl_FrameBuffer)& theFbo,
  54                                                       Image_PixMap& theImage,
  55                                                       Graphic3d_BufferType theBufferType);
  56
  57 public:
  58
  59   //! Empty constructor
  60   Standard_EXPORT OpenGl_FrameBuffer();
  61
  62   //! Destructor
  63   Standard_EXPORT virtual ~OpenGl_FrameBuffer();
  64
  65   //! Destroy object - will release GPU memory if any.
  66   Standard_EXPORT virtual void Release (OpenGl_Context* theGlCtx) Standard_OVERRIDE;
  67
  68   //! Number of multisampling samples.
  69   Standard_Integer NbSamples() const { return myNbSamples; }
  70
  71   //! Number of color buffers.
  72   Standard_Integer NbColorBuffers() const { return myColorTextures.Length(); }
  73
  74   //! Return true if FBO has been created with color attachment.
  75   bool HasColor() const { return !myColorFormats.IsEmpty(); }
  76
  77   //! Return true if FBO has been created with depth attachment.
  78   bool HasDepth() const { return myDepthFormat != 0; }
  79
  80   //! Return textures width x height.
  81   Graphic3d_Vec2i GetSize() const { return Graphic3d_Vec2i (GetSizeX(), GetSizeY()); }
  82
  83   //! Textures width.
  84   Standard_EXPORT Standard_Integer GetSizeX() const;
  85
  86   //! Textures height.
  87   Standard_EXPORT Standard_Integer GetSizeY() const;
  88
  89   //! Return viewport width x height.
  90   Graphic3d_Vec2i GetVPSize() const { return Graphic3d_Vec2i (myVPSizeX, myVPSizeY); }
  91
  92   //! Viewport width.
  93   Standard_Integer GetVPSizeX() const { return myVPSizeX; }
  94
  95   //! Viewport height.
  96   Standard_Integer GetVPSizeY() const { return myVPSizeY; }
  97
  98   //! Return viewport width x height.
  99   Graphic3d_Vec2i GetInitVPSize() const { return Graphic3d_Vec2i (myInitVPSizeX, myInitVPSizeY); }
 100
 101   //! Viewport width.
 102   Standard_Integer GetInitVPSizeX() const { return myInitVPSizeX; }
 103
 104   //! Viewport height.
 105   Standard_Integer GetInitVPSizeY() const { return myInitVPSizeY; }
 106
 107   //! Returns true if current object was initialized
 108   Standard_Boolean IsValid() const
 109   {
 110     return isValidFrameBuffer();
 111   }
 112
 113   //! Initialize FBO for rendering into single/multiple color buffer and depth textures.
 114   //! @param theGlCtx               currently bound OpenGL context
 115   //! @param theSize                texture width x height
 116   //! @param theColorFormats        list of color texture sized format (0 means no color attachment), e.g. GL_RGBA8
 117   //! @param theDepthStencilTexture depth-stencil texture
 118   //! @param theNbSamples           MSAA number of samples (0 means normal texture)
 119   //! @return true on success
 120   Standard_EXPORT Standard_Boolean Init (const Handle(OpenGl_Context)& theGlCtx,
 121                                          const Graphic3d_Vec2i&        theSize,
 122                                          const OpenGl_ColorFormats&    theColorFormats,
 123                                          const Handle(OpenGl_Texture)& theDepthStencilTexture,
 124                                          const Standard_Integer        theNbSamples = 0);
 125
 126   //! Initialize FBO for rendering into textures.
 127   //! @param theGlCtx       currently bound OpenGL context
 128   //! @param theSize        texture width x height
 129   //! @param theColorFormat color         texture sized format (0 means no color attachment), e.g. GL_RGBA8
 130   //! @param theDepthFormat depth-stencil texture sized format (0 means no depth attachment), e.g. GL_DEPTH24_STENCIL8
 131   //! @param theNbSamples   MSAA number of samples (0 means normal texture)
 132   //! @return true on success
 133   Standard_EXPORT Standard_Boolean Init (const Handle(OpenGl_Context)& theGlCtx,
 134                                          const Graphic3d_Vec2i& theSize,
 135                                          const Standard_Integer theColorFormat,
 136                                          const Standard_Integer theDepthFormat,
 137                                          const Standard_Integer theNbSamples = 0);
 138
 139   //! Initialize FBO for rendering into single/multiple color buffer and depth textures.
 140   //! @param theGlCtx        currently bound OpenGL context
 141   //! @param theSize         texture width x height
 142   //! @param theColorFormats list of color texture sized format (0 means no color attachment), e.g. GL_RGBA8
 143   //! @param theDepthFormat  depth-stencil texture sized format (0 means no depth attachment), e.g. GL_DEPTH24_STENCIL8
 144   //! @param theNbSamples    MSAA number of samples (0 means normal texture)
 145   //! @return true on success
 146   Standard_EXPORT Standard_Boolean Init (const Handle(OpenGl_Context)& theGlCtx,
 147                                          const Graphic3d_Vec2i&        theSize,
 148                                          const OpenGl_ColorFormats&    theColorFormats,
 149                                          const Standard_Integer        theDepthFormat,
 150                                          const Standard_Integer        theNbSamples = 0);
 151
 152   //! (Re-)initialize FBO with specified dimensions.
 153   Standard_EXPORT Standard_Boolean InitLazy (const Handle(OpenGl_Context)& theGlCtx,
 154                                              const Graphic3d_Vec2i& theViewportSize,
 155                                              const Standard_Integer theColorFormat,
 156                                              const Standard_Integer theDepthFormat,
 157                                              const Standard_Integer theNbSamples = 0);
 158
 159   //! (Re-)initialize FBO with specified dimensions.
 160   Standard_EXPORT Standard_Boolean InitLazy (const Handle(OpenGl_Context)& theGlCtx,
 161                                              const Graphic3d_Vec2i&        theViewportSize,
 162                                              const OpenGl_ColorFormats&    theColorFormats,
 163                                              const Standard_Integer        theDepthFormat,
 164                                              const Standard_Integer        theNbSamples = 0);
 165
 166   //! (Re-)initialize FBO with properties taken from another FBO.
 167   Standard_Boolean InitLazy (const Handle(OpenGl_Context)& theGlCtx,
 168                              const OpenGl_FrameBuffer&     theFbo)
 169   {
 170     return InitLazy (theGlCtx, Graphic3d_Vec2i (theFbo.myVPSizeX, theFbo.myVPSizeY), theFbo.myColorFormats, theFbo.myDepthFormat, theFbo.myNbSamples);
 171   }
 172
 173   //! (Re-)initialize FBO with specified dimensions.
 174   //! The Render Buffer Objects will be used for Color, Depth and Stencil attachments (as opposite to textures).
 175   //! @param theGlCtx       currently bound OpenGL context
 176   //! @param theSize        render buffer width x height
 177   //! @param theColorFormat color         render buffer sized format, e.g. GL_RGBA8
 178   //! @param theDepthFormat depth-stencil render buffer sized format, e.g. GL_DEPTH24_STENCIL8
 179   //! @param theColorRBufferFromWindow when specified - should be ID of already initialized RB object, which will be released within this class
 180   Standard_EXPORT Standard_Boolean InitWithRB (const Handle(OpenGl_Context)& theGlCtx,
 181                                                const Graphic3d_Vec2i& theSize,
 182                                                const Standard_Integer theColorFormat,
 183                                                const Standard_Integer theDepthFormat,
 184                                                const unsigned int     theColorRBufferFromWindow = 0);
 185
 186   //! Initialize class from currently bound FBO.
 187   //! Retrieved OpenGL objects will not be destroyed on Release.
 188   Standard_EXPORT Standard_Boolean InitWrapper (const Handle(OpenGl_Context)& theGlCtx);
 189
 190   //! Wrap existing color textures.
 191   Standard_EXPORT Standard_Boolean InitWrapper (const Handle(OpenGl_Context)& theGlContext,
 192                                                 const NCollection_Sequence<Handle(OpenGl_Texture)>& theColorTextures,
 193                                                 const Handle(OpenGl_Texture)& theDepthTexture = Handle(OpenGl_Texture)());
 194
 195   //! Setup viewport to render into FBO
 196   Standard_EXPORT void SetupViewport (const Handle(OpenGl_Context)& theGlCtx);
 197
 198   //! Override viewport settings
 199   Standard_EXPORT void ChangeViewport (const Standard_Integer theVPSizeX,
 200                                        const Standard_Integer theVPSizeY);
 201
 202   //! Bind frame buffer for drawing and reading (to render into the texture).
 203   Standard_EXPORT virtual void BindBuffer (const Handle(OpenGl_Context)& theGlCtx);
 204
 205   //! Bind frame buffer for drawing GL_DRAW_FRAMEBUFFER (to render into the texture).
 206   Standard_EXPORT virtual void BindDrawBuffer (const Handle(OpenGl_Context)& theGlCtx);
 207
 208   //! Bind frame buffer for reading GL_READ_FRAMEBUFFER
 209   Standard_EXPORT virtual void BindReadBuffer (const Handle(OpenGl_Context)& theGlCtx);
 210
 211   //! Unbind frame buffer.
 212   Standard_EXPORT virtual void UnbindBuffer (const Handle(OpenGl_Context)& theGlCtx);
 213
 214   //! Returns the color texture for the given color buffer index.
 215   const Handle(OpenGl_Texture)& ColorTexture (const Standard_Integer theColorBufferIndex = 0) const
 216   {
 217     return myColorTextures.Value (theColorBufferIndex);
 218   }
 219
 220   //! Returns the depth-stencil texture.
 221   const Handle(OpenGl_Texture)& DepthStencilTexture() const { return myDepthStencilTexture; }
 222
 223   //! Returns the color Render Buffer.
 224   unsigned int ColorRenderBuffer() const { return myGlColorRBufferId; }
 225
 226   //! Returns the depth Render Buffer.
 227   unsigned int DepthStencilRenderBuffer() const { return myGlDepthRBufferId; }
 228
 229   //! Returns estimated GPU memory usage for holding data without considering overheads and allocation alignment rules.
 230   Standard_EXPORT virtual Standard_Size EstimatedDataSize() const Standard_OVERRIDE;
 231
 232 public:
 233
 234   //! Initialize FBO for rendering into single/multiple color buffer and depth textures.
 235   Standard_DEPRECATED("Obsolete method, use Init() taking Graphic3d_Vec2i")
 236   bool Init (const Handle(OpenGl_Context)& theGlCtx,
 237              const Standard_Integer        theSizeX,
 238              const Standard_Integer        theSizeY,
 239              const OpenGl_ColorFormats&    theColorFormats,
 240              const Handle(OpenGl_Texture)& theDepthStencilTexture,
 241              const Standard_Integer        theNbSamples = 0)
 242   {
 243     return Init (theGlCtx, Graphic3d_Vec2i (theSizeX, theSizeY), theColorFormats, theDepthStencilTexture, theNbSamples);
 244   }
 245
 246   //! Initialize FBO for rendering into textures.
 247   Standard_DEPRECATED("Obsolete method, use Init() taking Graphic3d_Vec2i")
 248   bool Init (const Handle(OpenGl_Context)& theGlCtx,
 249              const Standard_Integer theSizeX,
 250              const Standard_Integer theSizeY,
 251              const Standard_Integer theColorFormat,
 252              const Standard_Integer theDepthFormat,
 253              const Standard_Integer theNbSamples = 0)
 254   {
 255     return Init (theGlCtx, Graphic3d_Vec2i (theSizeX, theSizeY), theColorFormat, theDepthFormat, theNbSamples);
 256   }
 257
 258   //! Initialize FBO for rendering into single/multiple color buffer and depth textures.
 259   Standard_DEPRECATED("Obsolete method, use Init() taking Graphic3d_Vec2i")
 260   bool Init (const Handle(OpenGl_Context)& theGlCtx,
 261              const Standard_Integer        theSizeX,
 262              const Standard_Integer        theSizeY,
 263              const OpenGl_ColorFormats&    theColorFormats,
 264              const Standard_Integer        theDepthFormat,
 265              const Standard_Integer        theNbSamples = 0)
 266   {
 267     return Init (theGlCtx, Graphic3d_Vec2i (theSizeX, theSizeY), theColorFormats, theDepthFormat, theNbSamples);
 268   }
 269
 270   //! (Re-)initialize FBO with specified dimensions.
 271   Standard_DEPRECATED("Obsolete method, use InitLazy() taking Graphic3d_Vec2i")
 272   bool InitLazy (const Handle(OpenGl_Context)& theGlCtx,
 273                  const Standard_Integer theViewportSizeX,
 274                  const Standard_Integer theViewportSizeY,
 275                  const Standard_Integer theColorFormat,
 276                  const Standard_Integer theDepthFormat,
 277                  const Standard_Integer theNbSamples = 0)
 278   {
 279     return InitLazy (theGlCtx, Graphic3d_Vec2i (theViewportSizeX, theViewportSizeY), theColorFormat, theDepthFormat, theNbSamples);
 280   }
 281
 282   //! (Re-)initialize FBO with specified dimensions.
 283   Standard_DEPRECATED("Obsolete method, use InitLazy() taking Graphic3d_Vec2i")
 284   bool InitLazy (const Handle(OpenGl_Context)& theGlCtx,
 285                  const Standard_Integer        theViewportSizeX,
 286                  const Standard_Integer        theViewportSizeY,
 287                  const OpenGl_ColorFormats&    theColorFormats,
 288                  const Standard_Integer        theDepthFormat,
 289                  const Standard_Integer        theNbSamples = 0)
 290   {
 291     return InitLazy (theGlCtx, Graphic3d_Vec2i (theViewportSizeX, theViewportSizeY), theColorFormats, theDepthFormat, theNbSamples);
 292   }
 293
 294   //! (Re-)initialize FBO with specified dimensions.
 295   //! The Render Buffer Objects will be used for Color, Depth and Stencil attachments (as opposite to textures).
 296   Standard_DEPRECATED("Obsolete method, use InitWithRB() taking Graphic3d_Vec2i")
 297   bool InitWithRB (const Handle(OpenGl_Context)& theGlCtx,
 298                    const Standard_Integer theSizeX,
 299                    const Standard_Integer theSizeY,
 300                    const Standard_Integer theColorFormat,
 301                    const Standard_Integer theDepthFormat,
 302                    const unsigned int     theColorRBufferFromWindow = 0)
 303   {
 304     return InitWithRB (theGlCtx, Graphic3d_Vec2i (theSizeX, theSizeY), theColorFormat, theDepthFormat, theColorRBufferFromWindow);
 305   }
 306
 307 protected:
 308
 309   Standard_Boolean isValidFrameBuffer() const
 310   {
 311     return myGlFBufferId != NO_FRAMEBUFFER;
 312   }
 313
 314 protected:
 315
 316   typedef NCollection_Vector<Handle(OpenGl_Texture)> OpenGl_TextureArray;
 317
 318 protected:
 319
 320   Standard_Integer       myInitVPSizeX;         //!< viewport width  specified during initialization (kept even on failure)
 321   Standard_Integer       myInitVPSizeY;         //!< viewport height specified during initialization (kept even on failure)
 322   Standard_Integer       myVPSizeX;             //!< viewport width  (should be <= texture width)
 323   Standard_Integer       myVPSizeY;             //!< viewport height (should be <= texture height)
 324   Standard_Integer       myNbSamples;           //!< number of MSAA samples
 325   OpenGl_ColorFormats    myColorFormats;        //!< sized format for color         texture, GL_RGBA8 by default
 326   Standard_Integer       myDepthFormat;         //!< sized format for depth-stencil texture, GL_DEPTH24_STENCIL8 by default
 327   unsigned int           myGlFBufferId;         //!< FBO object ID
 328   unsigned int           myGlColorRBufferId;    //!< color         Render Buffer object (alternative to myColorTexture)
 329   unsigned int           myGlDepthRBufferId;    //!< depth-stencil Render Buffer object (alternative to myDepthStencilTexture)
 330   bool                   myIsOwnBuffer;         //!< flag indicating that FBO should be deallocated by this class
 331   bool                   myIsOwnColor;          //!< flag indicating that color textures should be deallocated by this class
 332   bool                   myIsOwnDepth;          //!< flag indicating that depth texture  should be deallocated by this class
 333   OpenGl_TextureArray    myColorTextures;       //!< color texture objects
 334   Handle(OpenGl_Texture) myDepthStencilTexture; //!< depth-stencil texture object
 335
 336 public:
 337
 338   DEFINE_STANDARD_RTTIEXT(OpenGl_FrameBuffer,OpenGl_Resource) // Type definition
 339
 340 };
 341
 342 #endif // OPENGL_FRAME_BUFFER_H