1 // Created by: Kirill GAVRILOV
2 // Copyright (c) 2013-2014 OPEN CASCADE SAS
4 // This file is part of Open CASCADE Technology software library.
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.
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
15 #ifndef _OpenGl_Texture_H__
16 #define _OpenGl_Texture_H__
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>
25 class Graphic3d_TextureParams;
29 class OpenGl_Texture : public OpenGl_NamedResource
31 DEFINE_STANDARD_RTTIEXT(OpenGl_Texture, OpenGl_NamedResource)
35 static const GLuint NO_TEXTURE = 0;
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);
44 //! Create uninitialized texture.
45 Standard_EXPORT OpenGl_Texture (const TCollection_AsciiString& theResourceId = TCollection_AsciiString(),
46 const Handle(Graphic3d_TextureParams)& theParams = Handle(Graphic3d_TextureParams)());
49 Standard_EXPORT virtual ~OpenGl_Texture();
51 //! @return true if current object was initialized
52 virtual bool IsValid() const { return myTextureId != NO_TEXTURE; }
54 //! @return target to which the texture is bound (GL_TEXTURE_1D, GL_TEXTURE_2D)
55 GLenum GetTarget() const { return myTarget; }
57 //! @return texture width (0 LOD)
58 GLsizei SizeX() const { return mySizeX; }
60 //! @return texture height (0 LOD)
61 GLsizei SizeY() const { return mySizeY; }
63 //! @return texture ID
64 GLuint TextureId() const { return myTextureId; }
66 //! @return texture format (not sized)
67 GLenum GetFormat() const { return myTextFormat; }
69 //! @return texture format (sized)
70 GLint SizedFormat() const { return mySizedFormat; }
72 //! Return true for GL_RED and GL_ALPHA formats.
73 bool IsAlpha() const { return myIsAlpha; }
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; }
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; }
83 //! Set if 2D surface is defined top-down (TRUE) or bottom-up (FALSE).
84 void SetTopDown (bool theIsTopDown) { myIsTopDown = theIsTopDown; }
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);
90 //! Destroy object - will release GPU memory if any.
91 Standard_EXPORT virtual void Release (OpenGl_Context* theCtx) Standard_OVERRIDE;
93 //! Return texture sampler.
94 const Handle(OpenGl_Sampler)& Sampler() const { return mySampler; }
96 //! Set texture sampler.
97 void SetSampler (const Handle(OpenGl_Sampler)& theSampler) { mySampler = theSampler; }
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);
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
107 Bind (theCtx, mySampler->Parameters()->TextureUnit());
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
114 Unbind (theCtx, mySampler->Parameters()->TextureUnit());
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;
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;
127 //! Revision of associated data source.
128 Standard_Size Revision() const { return myRevision; }
130 //! Set revision of associated data source.
131 void SetRevision (const Standard_Size theRevision) { myRevision = theRevision; }
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);
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);
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);
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);
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);
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);
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);
179 //! @return true if texture was generated within mipmaps
180 Standard_Boolean HasMipmaps() const { return myMaxMipLevel > 0; }
182 //! Return upper mipmap level index (0 means no mipmaps).
183 Standard_Integer MaxMipmapLevel() const { return myMaxMipLevel; }
185 //! Return number of MSAA samples.
186 Standard_Integer NbSamples() const { return myNbSamples; }
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;
191 //! Returns TRUE for point sprite texture.
192 virtual bool IsPointSprite() const { return false; }
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;
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,
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();
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,
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();
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)
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);
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)
259 return Init (theCtx, theImage, theType, true);
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)
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);
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);
297 //! Apply default sampler parameters after texture creation.
298 Standard_EXPORT void applyDefaultSamplerParams (const Handle(OpenGl_Context)& theCtx);
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)
318 DEFINE_STANDARD_HANDLE(OpenGl_Texture, OpenGl_NamedResource)
320 #endif // _OpenGl_Texture_H__