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