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   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 interprete 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   //! Creates Texture id if not yet generated.
  80   //! Data should be initialized by another method.
  81   Standard_EXPORT bool Create (const Handle(OpenGl_Context)& theCtx);
  82
  83   //! Destroy object - will release GPU memory if any.
  84   Standard_EXPORT virtual void Release (OpenGl_Context* theCtx) Standard_OVERRIDE;
  85
  86   //! Return texture sampler.
  87   const Handle(OpenGl_Sampler)& Sampler() const { return mySampler; }
  88
  89   //! Set texture sampler.
  90   void SetSampler (const Handle(OpenGl_Sampler)& theSampler) { mySampler = theSampler; }
  91
  92   //! Initialize the Sampler Object (as OpenGL object).
  93   //! @param theCtx currently bound OpenGL context
  94   Standard_EXPORT bool InitSamplerObject (const Handle(OpenGl_Context)& theCtx);
  95
  96   //! Bind this Texture to the unit specified in sampler parameters.
  97   //! Also binds Sampler Object if it is allocated.
  98   void Bind (const Handle(OpenGl_Context)& theCtx) const
  99   {
 100     Bind (theCtx, mySampler->Parameters()->TextureUnit());
 101   }
 102
 103   //! Unbind texture from the unit specified in sampler parameters.
 104   //! Also unbinds Sampler Object if it is allocated.
 105   void Unbind (const Handle(OpenGl_Context)& theCtx) const
 106   {
 107     Unbind (theCtx, mySampler->Parameters()->TextureUnit());
 108   }
 109
 110   //! Bind this Texture to specified unit.
 111   //! Also binds Sampler Object if it is allocated.
 112   Standard_EXPORT void Bind (const Handle(OpenGl_Context)& theCtx,
 113                              const Graphic3d_TextureUnit   theTextureUnit) const;
 114
 115   //! Unbind texture from specified unit.
 116   //! Also unbinds Sampler Object if it is allocated.
 117   Standard_EXPORT void Unbind (const Handle(OpenGl_Context)& theCtx,
 118                                const Graphic3d_TextureUnit   theTextureUnit) const;
 119
 120   //! Revision of associated data source.
 121   Standard_Size Revision() const { return myRevision; }
 122
 123   //! Set revision of associated data source.
 124   void SetRevision (const Standard_Size theRevision) { myRevision = theRevision; }
 125
 126   //! Notice that texture will be unbound after this call.
 127   Standard_EXPORT bool Init (const Handle(OpenGl_Context)& theCtx,
 128                              const Image_PixMap&           theImage,
 129                              const Graphic3d_TypeOfTexture theType,
 130                              const Standard_Boolean        theIsColorMap);
 131
 132   //! Initialize the texture with specified format, size and texture type.
 133   //! If theImage is empty the texture data will contain trash.
 134   //! Notice that texture will be unbound after this call.
 135   Standard_EXPORT bool Init (const Handle(OpenGl_Context)& theCtx,
 136                              const OpenGl_TextureFormat&   theFormat,
 137                              const Graphic3d_Vec2i&        theSizeXY,
 138                              const Graphic3d_TypeOfTexture theType,
 139                              const Image_PixMap*           theImage = NULL);
 140
 141   //! Initialize the texture with Graphic3d_TextureMap.
 142   //! It is an universal way to initialize.
 143   //! Sitable initialization method will be chosen.
 144   Standard_EXPORT bool Init (const Handle(OpenGl_Context)&       theCtx,
 145                              const Handle(Graphic3d_TextureMap)& theTextureMap);
 146
 147   //! Initialize the 2D multisampling texture using glTexImage2DMultisample().
 148   Standard_EXPORT bool Init2DMultisample (const Handle(OpenGl_Context)& theCtx,
 149                                           const GLsizei                 theNbSamples,
 150                                           const GLint                   theTextFormat,
 151                                           const GLsizei                 theSizeX,
 152                                           const GLsizei                 theSizeY);
 153
 154   //! Allocates texture rectangle with specified format and size.
 155   //! \note Texture data is not initialized (will contain trash).
 156   Standard_EXPORT bool InitRectangle (const Handle(OpenGl_Context)& theCtx,
 157                                       const Standard_Integer        theSizeX,
 158                                       const Standard_Integer        theSizeY,
 159                                       const OpenGl_TextureFormat&   theFormat);
 160
 161   //! Initializes 3D texture rectangle with specified format and size.
 162   Standard_EXPORT bool Init3D (const Handle(OpenGl_Context)& theCtx,
 163                                const OpenGl_TextureFormat&   theFormat,
 164                                const Graphic3d_Vec3i&        theSizeXYZ,
 165                                const void*                   thePixels);
 166
 167   //! @return true if texture was generated within mipmaps
 168   Standard_Boolean HasMipmaps() const { return myHasMipmaps; }
 169
 170   //! Returns estimated GPU memory usage for holding data without considering overheads and allocation alignment rules.
 171   Standard_EXPORT virtual Standard_Size EstimatedDataSize() const Standard_OVERRIDE;
 172
 173   //! Returns TRUE for point sprite texture.
 174   virtual bool IsPointSprite() const { return false; }
 175
 176 public:
 177
 178   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat::FindFormat() should be used instead")
 179   static bool GetDataFormat (const Handle(OpenGl_Context)& theCtx,
 180                              const Image_Format            theFormat,
 181                              GLint&                        theTextFormat,
 182                              GLenum&                       thePixelFormat,
 183                              GLenum&                       theDataType)
 184   {
 185     OpenGl_TextureFormat aFormat = OpenGl_TextureFormat::FindFormat (theCtx, theFormat, false);
 186     theTextFormat  = aFormat.InternalFormat();
 187     thePixelFormat = aFormat.PixelFormat();
 188     theDataType    = aFormat.DataType();
 189     return aFormat.IsValid();
 190   }
 191
 192   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat::FindFormat() should be used instead")
 193   static bool GetDataFormat (const Handle(OpenGl_Context)& theCtx,
 194                              const Image_PixMap&           theData,
 195                              GLint&                        theTextFormat,
 196                              GLenum&                       thePixelFormat,
 197                              GLenum&                       theDataType)
 198   {
 199     OpenGl_TextureFormat aFormat = OpenGl_TextureFormat::FindFormat (theCtx, theData.Format(), false);
 200     theTextFormat  = aFormat.InternalFormat();
 201     thePixelFormat = aFormat.PixelFormat();
 202     theDataType    = aFormat.DataType();
 203     return aFormat.IsValid();
 204   }
 205
 206   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat should be passed instead of separate parameters")
 207   bool Init (const Handle(OpenGl_Context)& theCtx,
 208              const GLint                   theTextFormat,
 209              const GLenum                  thePixelFormat,
 210              const GLenum                  theDataType,
 211              const GLsizei                 theSizeX,
 212              const GLsizei                 theSizeY,
 213              const Graphic3d_TypeOfTexture theType,
 214              const Image_PixMap*           theImage = NULL)
 215   {
 216     OpenGl_TextureFormat aFormat;
 217     aFormat.SetInternalFormat (theTextFormat);
 218     aFormat.SetPixelFormat (thePixelFormat);
 219     aFormat.SetDataType (theDataType);
 220     return Init (theCtx, aFormat, Graphic3d_Vec2i (theSizeX, theSizeY), theType, theImage);
 221   }
 222
 223   Standard_DEPRECATED("Deprecated method, theIsColorMap parameter should be explicitly specified")
 224   bool Init (const Handle(OpenGl_Context)& theCtx,
 225              const Image_PixMap& theImage,
 226              const Graphic3d_TypeOfTexture theType)
 227   {
 228     return Init (theCtx, theImage, theType, true);
 229   }
 230
 231   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat should be passed instead of separate parameters")
 232   bool Init3D (const Handle(OpenGl_Context)& theCtx,
 233                const GLint  theTextFormat,
 234                const GLenum thePixelFormat,
 235                const GLenum theDataType,
 236                const Standard_Integer theSizeX,
 237                const Standard_Integer theSizeY,
 238                const Standard_Integer theSizeZ,
 239                const void* thePixels)
 240   {
 241     OpenGl_TextureFormat aFormat;
 242     aFormat.SetInternalFormat (theTextFormat);
 243     aFormat.SetPixelFormat (thePixelFormat);
 244     aFormat.SetDataType (theDataType);
 245     return Init3D (theCtx, aFormat, Graphic3d_Vec3i (theSizeX, theSizeY, theSizeZ), thePixels);
 246   }
 247
 248 protected:
 249
 250   //! Apply default sampler parameters after texture creation.
 251   Standard_EXPORT void applyDefaultSamplerParams (const Handle(OpenGl_Context)& theCtx);
 252
 253   //! Initializes 6 sides of cubemap.
 254   //! If theCubeMap is not NULL then size and format will be taken from it and corresponding arguments will be ignored.
 255   //! Otherwise this parametres will be taken from arguments.
 256   //! @param theCtx         [in] active OpenGL context
 257   //! @param theCubeMap     [in] cubemap definition, can be NULL
 258   //! @param theSize        [in] cubemap dimensions
 259   //! @param theFormat      [in] image format
 260   //! @param theToGenMipmap [in] flag to generate mipmaped cubemap
 261   //! @param theIsColorMap  [in] flag indicating cubemap storing color values
 262   Standard_EXPORT bool initCubeMap (const Handle(OpenGl_Context)&    theCtx,
 263                                     const Handle(Graphic3d_CubeMap)& theCubeMap,
 264                                     Standard_Size    theSize,
 265                                     Image_Format     theFormat,
 266                                     Standard_Boolean theToGenMipmap,
 267                                     Standard_Boolean theIsColorMap);
 268
 269 protected:
 270
 271   Handle(OpenGl_Sampler) mySampler; //!< texture sampler
 272   Standard_Size    myRevision;   //!< revision of associated data source
 273   GLuint           myTextureId;  //!< GL resource ID
 274   GLenum           myTarget;     //!< GL_TEXTURE_1D/GL_TEXTURE_2D/GL_TEXTURE_3D
 275   GLsizei          mySizeX;      //!< texture width
 276   GLsizei          mySizeY;      //!< texture height
 277   GLsizei          mySizeZ;      //!< texture depth
 278   GLenum           myTextFormat; //!< texture format - GL_RGB, GL_RGBA,...
 279   GLint            mySizedFormat;//!< internal (sized) texture format
 280   Standard_Integer myNbSamples;  //!< number of MSAA samples
 281   Standard_Boolean myHasMipmaps; //!< flag indicates that texture was uploaded with mipmaps
 282   bool             myIsAlpha;    //!< indicates alpha format
 283
 284 };
 285
 286 DEFINE_STANDARD_HANDLE(OpenGl_Texture, OpenGl_NamedResource)
 287
 288 #endif // _OpenGl_Texture_H__