0031478: Visualization, TKOpenGl - allow uploading Cubemap in compressed DDS format...
[occt.git] / 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 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__