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   //! Return number of MSAA samples.
 186   Standard_Integer NbSamples() const { return myNbSamples; }
 187
 188   //! Returns estimated GPU memory usage for holding data without considering overheads and allocation alignment rules.
 189   Standard_EXPORT virtual Standard_Size EstimatedDataSize() const Standard_OVERRIDE;
 190
 191   //! Returns TRUE for point sprite texture.
 192   virtual bool IsPointSprite() const { return false; }
 193
 194   //! Auxiliary method for making an image dump from texture data.
 195   //! @param theImage   [out] result image data (will be overridden)
 196   //! @param theCtx      [in] active GL context
 197   //! @param theTexUnit  [in] texture slot to use
 198   //! @param theLevel    [in] mipmap level to dump
 199   //! @param theCubeSide [in] cubemap side to dump within [0, 5] range
 200   //! @return FALSE on error
 201   Standard_EXPORT bool ImageDump (Image_PixMap& theImage,
 202                                   const Handle(OpenGl_Context)& theCtx,
 203                                   Graphic3d_TextureUnit theTexUnit,
 204                                   Standard_Integer theLevel = 0,
 205                                   Standard_Integer theCubeSide = 0) const;
 206
 207 public:
 208
 209   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat::FindFormat() should be used instead")
 210   static bool GetDataFormat (const Handle(OpenGl_Context)& theCtx,
 211                              const Image_Format            theFormat,
 212                              GLint&                        theTextFormat,
 213                              GLenum&                       thePixelFormat,
 214                              GLenum&                       theDataType)
 215   {
 216     OpenGl_TextureFormat aFormat = OpenGl_TextureFormat::FindFormat (theCtx, theFormat, false);
 217     theTextFormat  = aFormat.InternalFormat();
 218     thePixelFormat = aFormat.PixelFormat();
 219     theDataType    = aFormat.DataType();
 220     return aFormat.IsValid();
 221   }
 222
 223   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat::FindFormat() should be used instead")
 224   static bool GetDataFormat (const Handle(OpenGl_Context)& theCtx,
 225                              const Image_PixMap&           theData,
 226                              GLint&                        theTextFormat,
 227                              GLenum&                       thePixelFormat,
 228                              GLenum&                       theDataType)
 229   {
 230     OpenGl_TextureFormat aFormat = OpenGl_TextureFormat::FindFormat (theCtx, theData.Format(), false);
 231     theTextFormat  = aFormat.InternalFormat();
 232     thePixelFormat = aFormat.PixelFormat();
 233     theDataType    = aFormat.DataType();
 234     return aFormat.IsValid();
 235   }
 236
 237   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat should be passed instead of separate parameters")
 238   bool Init (const Handle(OpenGl_Context)& theCtx,
 239              const GLint                   theTextFormat,
 240              const GLenum                  thePixelFormat,
 241              const GLenum                  theDataType,
 242              const GLsizei                 theSizeX,
 243              const GLsizei                 theSizeY,
 244              const Graphic3d_TypeOfTexture theType,
 245              const Image_PixMap*           theImage = NULL)
 246   {
 247     OpenGl_TextureFormat aFormat;
 248     aFormat.SetInternalFormat (theTextFormat);
 249     aFormat.SetPixelFormat (thePixelFormat);
 250     aFormat.SetDataType (theDataType);
 251     return Init (theCtx, aFormat, Graphic3d_Vec2i (theSizeX, theSizeY), theType, theImage);
 252   }
 253
 254   Standard_DEPRECATED("Deprecated method, theIsColorMap parameter should be explicitly specified")
 255   bool Init (const Handle(OpenGl_Context)& theCtx,
 256              const Image_PixMap& theImage,
 257              const Graphic3d_TypeOfTexture theType)
 258   {
 259     return Init (theCtx, theImage, theType, true);
 260   }
 261
 262   Standard_DEPRECATED("Deprecated method, OpenGl_TextureFormat should be passed instead of separate parameters")
 263   bool Init3D (const Handle(OpenGl_Context)& theCtx,
 264                const GLint  theTextFormat,
 265                const GLenum thePixelFormat,
 266                const GLenum theDataType,
 267                const Standard_Integer theSizeX,
 268                const Standard_Integer theSizeY,
 269                const Standard_Integer theSizeZ,
 270                const void* thePixels)
 271   {
 272     OpenGl_TextureFormat aFormat;
 273     aFormat.SetInternalFormat (theTextFormat);
 274     aFormat.SetPixelFormat (thePixelFormat);
 275     aFormat.SetDataType (theDataType);
 276     return Init3D (theCtx, aFormat, Graphic3d_Vec3i (theSizeX, theSizeY, theSizeZ), thePixels);
 277   }
 278
 279   //! Initializes 6 sides of cubemap.
 280   //! If theCubeMap is not NULL then size and format will be taken from it and corresponding arguments will be ignored.
 281   //! Otherwise this parametres will be taken from arguments.
 282   //! @param theCtx         [in] active OpenGL context
 283   //! @param theCubeMap     [in] cubemap definition, can be NULL
 284   //! @param theSize        [in] cubemap dimensions
 285   //! @param theFormat      [in] image format
 286   //! @param theToGenMipmap [in] flag to generate mipmaped cubemap
 287   //! @param theIsColorMap  [in] flag indicating cubemap storing color values
 288   Standard_EXPORT bool InitCubeMap (const Handle(OpenGl_Context)&    theCtx,
 289                                     const Handle(Graphic3d_CubeMap)& theCubeMap,
 290                                     Standard_Size    theSize,
 291                                     Image_Format     theFormat,
 292                                     Standard_Boolean theToGenMipmap,
 293                                     Standard_Boolean theIsColorMap);
 294
 295 protected:
 296
 297   //! Apply default sampler parameters after texture creation.
 298   Standard_EXPORT void applyDefaultSamplerParams (const Handle(OpenGl_Context)& theCtx);
 299
 300 protected:
 301
 302   Handle(OpenGl_Sampler) mySampler; //!< texture sampler
 303   Standard_Size    myRevision;   //!< revision of associated data source
 304   GLuint           myTextureId;  //!< GL resource ID
 305   GLenum           myTarget;     //!< GL_TEXTURE_1D/GL_TEXTURE_2D/GL_TEXTURE_3D
 306   GLsizei          mySizeX;      //!< texture width
 307   GLsizei          mySizeY;      //!< texture height
 308   GLsizei          mySizeZ;      //!< texture depth
 309   GLenum           myTextFormat; //!< texture format - GL_RGB, GL_RGBA,...
 310   GLint            mySizedFormat;//!< internal (sized) texture format
 311   Standard_Integer myNbSamples;  //!< number of MSAA samples
 312   Standard_Integer myMaxMipLevel;//!< upper mipmap level index (0 means no mipmaps)
 313   bool             myIsAlpha;    //!< indicates alpha format
 314   bool             myIsTopDown;  //!< indicates if 2D surface is defined top-down (TRUE) or bottom-up (FALSE)
 315
 316 };
 317
 318 DEFINE_STANDARD_HANDLE(OpenGl_Texture, OpenGl_NamedResource)
 319
 320 #endif // _OpenGl_Texture_H__