src/OpenGl/OpenGl_Texture.hxx

   1 // Created by: Kirill GAVRILOV
   2 // Copyright (c) 2013-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_Texture_H__
  16 #define _OpenGl_Texture_H__
  17
  18 #include <Graphic3d_CubeMap.hxx>
  19 #include <OpenGl_TextureFormat.hxx>
  20 #include <OpenGl_NamedResource.hxx>
  21 #include <OpenGl_Sampler.hxx>
  22 #include <Graphic3d_TextureUnit.hxx>
  23 #include <Graphic3d_TypeOfTexture.hxx>
  24
  25 class Graphic3d_TextureParams;
  26 class Image_PixMap;
  27
  28 //! Texture resource.
  29 class OpenGl_Texture : public OpenGl_NamedResource
  30 {
  31   DEFINE_STANDARD_RTTIEXT(OpenGl_Texture, OpenGl_NamedResource)
  32 public:
  33
  34   //! Helpful constants
  35   static const GLuint NO_TEXTURE = 0;
  36
  37   //! Return pixel size of pixel format in bytes.
  38   //! Note that this method considers that OpenGL natively supports this pixel format,
  39   //! which might be not the case - in the latter case, actual pixel size might differ!
  40   Standard_EXPORT static Standard_Size PixelSizeOfPixelFormat (Standard_Integer theInternalFormat);
  41
  42 public:
  43
  44   //! Create uninitialized texture.
  45   Standard_EXPORT OpenGl_Texture (const TCollection_AsciiString& theResourceId = TCollection_AsciiString(),
  46                                   const Handle(Graphic3d_TextureParams)& theParams = Handle(Graphic3d_TextureParams)());
  47
  48   //! Destroy object.
  49   Standard_EXPORT virtual ~OpenGl_Texture();
  50
  51   //! @return true if current object was initialized
  52   virtual bool IsValid() const { return myTextureId != NO_TEXTURE; }
  53
  54   //! @return target to which the texture is bound (GL_TEXTURE_1D, GL_TEXTURE_2D)
  55   GLenum GetTarget() const { return myTarget; }
  56
  57   //! @return texture width (0 LOD)
  58   GLsizei SizeX() const { return mySizeX; }
  59
  60   //! @return texture height (0 LOD)
  61   GLsizei SizeY() const { return mySizeY; }
  62
  63   //! @return texture ID
  64   GLuint TextureId() const { return myTextureId; }
  65
  66   //! @return texture format (not sized)
  67   GLenum GetFormat() const { return myTextFormat; }
  68
  69   //! @return texture format (sized)
  70   GLint SizedFormat() const { return mySizedFormat; }
  71
  72   //! Return true for GL_RED and GL_ALPHA formats.
  73   bool IsAlpha() const { return myIsAlpha; }
  74
  75   //! Setup to interpret the format as Alpha by Shader Manager
  76   //! (should be GL_ALPHA within compatible context or GL_RED otherwise).
  77   void SetAlpha (const bool theValue) { myIsAlpha = theValue; }
  78
  79   //! Return if 2D surface is defined top-down (TRUE) or bottom-up (FALSE).
  80   //! Normally set from Image_PixMap::IsTopDown() within texture initialization.
  81   bool IsTopDown() const { return myIsTopDown; }
  82
  83   //! Set if 2D surface is defined top-down (TRUE) or bottom-up (FALSE).
  84   void SetTopDown (bool theIsTopDown) { myIsTopDown = theIsTopDown; }
  85
  86   //! Creates Texture id if not yet generated.
  87   //! Data should be initialized by another method.
  88   Standard_EXPORT bool Create (const Handle(OpenGl_Context)& theCtx);
  89
  90   //! Destroy object - will release GPU memory if any.
  91   Standard_EXPORT virtual void Release (OpenGl_Context* theCtx) Standard_OVERRIDE;
  92
  93   //! Return texture sampler.
  94   const Handle(OpenGl_Sampler)& Sampler() const { return mySampler; }
  95
  96   //! Set texture sampler.
  97   void SetSampler (const Handle(OpenGl_Sampler)& theSampler) { mySampler = theSampler; }
  98
  99   //! Initialize the Sampler Object (as OpenGL object).
 100   //! @param theCtx currently bound OpenGL context
 101   Standard_EXPORT bool InitSamplerObject (const Handle(OpenGl_Context)& theCtx);
 102
 103   //! Bind this Texture to the unit specified in sampler parameters.
 104   //! Also binds Sampler Object if it is allocated.
 105   void Bind (const Handle(OpenGl_Context)& theCtx) const
 106   {
 107     Bind (theCtx, mySampler->Parameters()->TextureUnit());
 108   }
 109
 110   //! Unbind texture from the unit specified in sampler parameters.
 111   //! Also unbinds Sampler Object if it is allocated.
 112   void Unbind (const Handle(OpenGl_Context)& theCtx) const
 113   {
 114     Unbind (theCtx, mySampler->Parameters()->TextureUnit());
 115   }
 116
 117   //! Bind this Texture to specified unit.
 118   //! Also binds Sampler Object if it is allocated.
 119   Standard_EXPORT void Bind (const Handle(OpenGl_Context)& theCtx,
 120                              const Graphic3d_TextureUnit   theTextureUnit) const;
 121
 122   //! Unbind texture from specified unit.
 123   //! Also unbinds Sampler Object if it is allocated.
 124   Standard_EXPORT void Unbind (const Handle(OpenGl_Context)& theCtx,
 125                                const Graphic3d_TextureUnit   theTextureUnit) const;
 126
 127   //! Revision of associated data source.
 128   Standard_Size Revision() const { return myRevision; }
 129
 130   //! Set revision of associated data source.
 131   void SetRevision (const Standard_Size theRevision) { myRevision = theRevision; }
 132
 133   //! Notice that texture will be unbound after this call.
 134   Standard_EXPORT bool Init (const Handle(OpenGl_Context)& theCtx,
 135                              const Image_PixMap&           theImage,
 136                              const Graphic3d_TypeOfTexture theType,
 137                              const Standard_Boolean        theIsColorMap);
 138
 139   //! Initialize the texture with specified format, size and texture type.
 140   //! If theImage is empty the texture data will contain trash.
 141   //! Notice that texture will be unbound after this call.
 142   Standard_EXPORT bool Init (const Handle(OpenGl_Context)& theCtx,
 143                              const OpenGl_TextureFormat&   theFormat,
 144                              const Graphic3d_Vec2i&        theSizeXY,
 145                              const Graphic3d_TypeOfTexture theType,
 146                              const Image_PixMap*           theImage = NULL);
 147
 148   //! Initialize the texture with Graphic3d_TextureMap.
 149   //! It is an universal way to initialize.
 150   //! Suitable initialization method will be chosen.
 151   Standard_EXPORT bool Init (const Handle(OpenGl_Context)&       theCtx,
 152                              const Handle(Graphic3d_TextureMap)& theTextureMap);
 153
 154   //! Initialize the texture with Image_CompressedPixMap.
 155   Standard_EXPORT bool InitCompressed (const Handle(OpenGl_Context)& theCtx,
 156                                        const Image_CompressedPixMap& theImage,
 157                                        const Standard_Boolean        theIsColorMap);
 158
 159   //! Initialize the 2D multisampling texture using glTexImage2DMultisample().
 160   Standard_EXPORT bool Init2DMultisample (const Handle(OpenGl_Context)& theCtx,
 161                                           const GLsizei                 theNbSamples,
 162                                           const GLint                   theTextFormat,
 163                                           const GLsizei                 theSizeX,
 164                                           const GLsizei                 theSizeY);
 165
 166   //! Allocates texture rectangle with specified format and size.
 167   //! \note Texture data is not initialized (will contain trash).
 168   Standard_EXPORT bool InitRectangle (const Handle(OpenGl_Context)& theCtx,
 169                                       const Standard_Integer        theSizeX,
 170                                       const Standard_Integer        theSizeY,
 171                                       const OpenGl_TextureFormat&   theFormat);
 172
 173   //! Initializes 3D texture rectangle with specified format and size.
 174   Standard_EXPORT bool Init3D (const Handle(OpenGl_Context)& theCtx,
 175                                const OpenGl_TextureFormat&   theFormat,
 176                                const Graphic3d_Vec3i&        theSizeXYZ,
 177                                const void*                   thePixels);
 178
 179   //! @return true if texture was generated within mipmaps
 180   Standard_Boolean HasMipmaps() const { return myMaxMipLevel > 0; }
 181
 182   //! Return upper mipmap level index (0 means no mipmaps).
 183   Standard_Integer MaxMipmapLevel() const { return myMaxMipLevel; }
 184
 185   //! Returns estimated GPU memory usage for holding data without considering overheads and allocation alignment rules.
 186   Standard_EXPORT virtual Standard_Size EstimatedDataSize() const Standard_OVERRIDE;
 187
 188   //! Returns TRUE for point sprite texture.
 189   virtual bool IsPointSprite() const { return false; }
 190
 191 public:
 192
 193   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat::FindFormat() should be used instead")
 194   static bool GetDataFormat (const Handle(OpenGl_Context)& theCtx,
 195                              const Image_Format            theFormat,
 196                              GLint&                        theTextFormat,
 197                              GLenum&                       thePixelFormat,
 198                              GLenum&                       theDataType)
 199   {
 200     OpenGl_TextureFormat aFormat = OpenGl_TextureFormat::FindFormat (theCtx, theFormat, false);
 201     theTextFormat  = aFormat.InternalFormat();
 202     thePixelFormat = aFormat.PixelFormat();
 203     theDataType    = aFormat.DataType();
 204     return aFormat.IsValid();
 205   }
 206
 207   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat::FindFormat() should be used instead")
 208   static bool GetDataFormat (const Handle(OpenGl_Context)& theCtx,
 209                              const Image_PixMap&           theData,
 210                              GLint&                        theTextFormat,
 211                              GLenum&                       thePixelFormat,
 212                              GLenum&                       theDataType)
 213   {
 214     OpenGl_TextureFormat aFormat = OpenGl_TextureFormat::FindFormat (theCtx, theData.Format(), false);
 215     theTextFormat  = aFormat.InternalFormat();
 216     thePixelFormat = aFormat.PixelFormat();
 217     theDataType    = aFormat.DataType();
 218     return aFormat.IsValid();
 219   }
 220
 221   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat should be passed instead of separate parameters")
 222   bool Init (const Handle(OpenGl_Context)& theCtx,
 223              const GLint                   theTextFormat,
 224              const GLenum                  thePixelFormat,
 225              const GLenum                  theDataType,
 226              const GLsizei                 theSizeX,
 227              const GLsizei                 theSizeY,
 228              const Graphic3d_TypeOfTexture theType,
 229              const Image_PixMap*           theImage = NULL)
 230   {
 231     OpenGl_TextureFormat aFormat;
 232     aFormat.SetInternalFormat (theTextFormat);
 233     aFormat.SetPixelFormat (thePixelFormat);
 234     aFormat.SetDataType (theDataType);
 235     return Init (theCtx, aFormat, Graphic3d_Vec2i (theSizeX, theSizeY), theType, theImage);
 236   }
 237
 238   Standard_DEPRECATED("Deprecated method, theIsColorMap parameter should be explicitly specified")
 239   bool Init (const Handle(OpenGl_Context)& theCtx,
 240              const Image_PixMap& theImage,
 241              const Graphic3d_TypeOfTexture theType)
 242   {
 243     return Init (theCtx, theImage, theType, true);
 244   }
 245
 246   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat should be passed instead of separate parameters")
 247   bool Init3D (const Handle(OpenGl_Context)& theCtx,
 248                const GLint  theTextFormat,
 249                const GLenum thePixelFormat,
 250                const GLenum theDataType,
 251                const Standard_Integer theSizeX,
 252                const Standard_Integer theSizeY,
 253                const Standard_Integer theSizeZ,
 254                const void* thePixels)
 255   {
 256     OpenGl_TextureFormat aFormat;
 257     aFormat.SetInternalFormat (theTextFormat);
 258     aFormat.SetPixelFormat (thePixelFormat);
 259     aFormat.SetDataType (theDataType);
 260     return Init3D (theCtx, aFormat, Graphic3d_Vec3i (theSizeX, theSizeY, theSizeZ), thePixels);
 261   }
 262
 263   //! Initializes 6 sides of cubemap.
 264   //! If theCubeMap is not NULL then size and format will be taken from it and corresponding arguments will be ignored.
 265   //! Otherwise this parametres will be taken from arguments.
 266   //! @param theCtx         [in] active OpenGL context
 267   //! @param theCubeMap     [in] cubemap definition, can be NULL
 268   //! @param theSize        [in] cubemap dimensions
 269   //! @param theFormat      [in] image format
 270   //! @param theToGenMipmap [in] flag to generate mipmaped cubemap
 271   //! @param theIsColorMap  [in] flag indicating cubemap storing color values
 272   Standard_EXPORT bool InitCubeMap (const Handle(OpenGl_Context)&    theCtx,
 273                                     const Handle(Graphic3d_CubeMap)& theCubeMap,
 274                                     Standard_Size    theSize,
 275                                     Image_Format     theFormat,
 276                                     Standard_Boolean theToGenMipmap,
 277                                     Standard_Boolean theIsColorMap);
 278
 279 protected:
 280
 281   //! Apply default sampler parameters after texture creation.
 282   Standard_EXPORT void applyDefaultSamplerParams (const Handle(OpenGl_Context)& theCtx);
 283
 284 protected:
 285
 286   Handle(OpenGl_Sampler) mySampler; //!< texture sampler
 287   Standard_Size    myRevision;   //!< revision of associated data source
 288   GLuint           myTextureId;  //!< GL resource ID
 289   GLenum           myTarget;     //!< GL_TEXTURE_1D/GL_TEXTURE_2D/GL_TEXTURE_3D
 290   GLsizei          mySizeX;      //!< texture width
 291   GLsizei          mySizeY;      //!< texture height
 292   GLsizei          mySizeZ;      //!< texture depth
 293   GLenum           myTextFormat; //!< texture format - GL_RGB, GL_RGBA,...
 294   GLint            mySizedFormat;//!< internal (sized) texture format
 295   Standard_Integer myNbSamples;  //!< number of MSAA samples
 296   Standard_Integer myMaxMipLevel;//!< upper mipmap level index (0 means no mipmaps)
 297   bool             myIsAlpha;    //!< indicates alpha format
 298   bool             myIsTopDown;  //!< indicates if 2D surface is defined top-down (TRUE) or bottom-up (FALSE)
 299
 300 };
 301
 302 DEFINE_STANDARD_HANDLE(OpenGl_Texture, OpenGl_NamedResource)
 303
 304 #endif // _OpenGl_Texture_H__