gml_GL_Texture.h

00001 // gml_GL_Texture.h --
00002 //
00003 //    Manage creation and update of OpenGL textures from GML bitmaps.
00004 //
00005 //  Copyright (c) 2004 CLIPS-IMAG
00006 //
00007 //  See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00008 //  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00009 //
00010 //  TODO:
00011 //    * asynchronous download
00012 //    * check for extensions: EXT_texture_rectangle, EXT_framebuffer_object, 
00013 //      ARB_pixel_buffer_object 
00014 //
00015 //  January 2005 (JL)
00016 //    Removed the Copy method (copying is now performed lazily by Enable()).
00017 //    Made textures robust to change in GL context (the texture will
00018 //    be re-uploaded if the context changes).
00019 //
00020 //  August 13, 2004 (FB)
00021 //    Renamed files from "gml_TextureGL.*" to "gml_GL_Texture.*".
00022 //    "Coords" and "NormalCoords" now return "void" (was "gml_TError").
00023 //    Renamed "Preflight" method into "SetBitmap".
00024 //    Added "UpdateFromBitmap" method.
00025 //    "Copy" only update the texture if necessary (addition of a "fDirty" flag).
00026 //
00027 //  Created on August, 3 2004 (JL).
00028 
00029 #ifndef __GML_GL_TEXTURE__
00030 #define __GML_GL_TEXTURE__
00031 
00032 #include "gml/base/gml_Errors.h"
00033 #include "gml/image/gml_Bitmap.h"
00034 #include "gml/image/gml_Geometry.h"
00035 #include "gml/gl/gml_GL_Base.h"
00036 
00037 ///
00038 /// gmlGL_TTexture --
00039 ///
00040 ///   Abstraction of OpenGL textures, that allows texture uploading from GML bitmaps.
00041 ///
00042 ///   @todo isolate the GL implementation of the texture from an abstract texture type.
00043 ///   The abstract type should only have "Init", "Dispose", "SetBitmap", "Update",
00044 ///   and "Exists" methods. The other ones are GL specific.
00045 ///
00046 class gmlGL_TTexture 
00047 {
00048 public:
00049 
00050   ///
00051   /// Init --
00052   ///   Zero the structure. No side effects.
00053   ///
00054   gml_TError Init ();
00055   
00056   ///
00057   /// Dispose --
00058   ///   Release the GL resources used by this texture, if any.
00059   ///
00060   ///   Can be called at any time.
00061   ///
00062   void Dispose ();
00063 
00064   ///
00065   /// Upload --
00066   ///   Copy the specified region <roi> of the <bitmap> to the texture.
00067   ///   The OpenGL texture may need to be re-created.
00068   ///
00069   ///   If <roi> is NULL, use the whole bitmap.
00070   ///
00071   ///   If <persistent> is false, this means that <bitmap> is not persistent and 
00072   ///   a private copy is made by the texture object.
00073   ///   If true, the bitmap is considered persistent until the deletion of the
00074   ///   texture object. Its early destruction will result un undefined behavior.
00075   ///
00076   ///   Return an error code if the <bitmap> has unsupported characteristics.
00077   ///
00078   ///   Can be called at any time.
00079   ///
00080   gml_TError Upload    (gml_TBitmap* bitmap, 
00081                         gml_TRect*   roi           = (gml_TRect*)NULL,
00082                         gml_TBoolean persistent    = gml_cFalse,
00083                         gml_TBoolean alphaTexture  = gml_cFalse);
00084   
00085   ///
00086   /// Download --
00087   ///   Copy the specified <source> region of the texture to the <dest> 
00088   ///   region of the <bitmap>.
00089   ///   Fails for non-RGB texture encodings. Fast only if both the
00090   ///   texture and the destination bitmap are 32-bit RGB.
00091   ///
00092   gml_TError Download  (gml_TBitmap* bitmap, 
00093                         gml_TRect*   source       = (gml_TRect*)NULL,
00094                         gml_TRect*   dest         = (gml_TRect*)NULL);
00095 
00096 
00097   ///
00098   /// BeginRenderTo --
00099   ///   Setup the sharing context so that GL operations draw to the texture.
00100   ///   As a side effect, the current context is set to the sharing context.
00101   ///
00102   gml_TError BeginRenderTo  ();
00103   
00104   ///
00105   /// EndRenderTo --
00106   ///   Commit render-to-texture operations.
00107   ///
00108   gml_TError EndRenderTo  ();
00109   
00110     
00111   ///
00112   /// UpdateFromBitmap --
00113   ///   Notify the texture that the bitmap's pixels have been modified and so 
00114   ////  the texture should update itseld from the bitmap.
00115   ///
00116   ///   Upload() must have been called since Init().
00117   ///
00118   ///   DEPRECATED.
00119   ///
00120   void UpdateFromBitmap ();
00121 
00122   ///
00123   /// Copy --
00124   ///   Copy region <source> of the texture to region <dest> of texture
00125   ///   <other>. Any of the two regions may be passed as NULL, in which case
00126   ///   the whole texture will be used.
00127   ///   The regions will be clamped to the bounding rectangles.
00128   ///   The regions need not be of the same size; the texture will be
00129   ///   scaled appropriately.
00130   ///
00131   gml_TError Copy (gmlGL_TTexture* other, 
00132                    gml_TRect*      source  = NULL, 
00133                    gml_TRect*      dest    = NULL, 
00134                    Float32*        transfo = NULL);
00135 
00136     
00137   ///
00138   /// Exists --
00139   ///   Return true if Upload() has successfully been called at least once.
00140   ///
00141   gml_TBoolean Exists ();  
00142 
00143 
00144   ///
00145   /// OpenGL specific methods
00146   ///
00147     
00148     
00149   ///
00150   /// Enable --
00151   ///   Prepare to render the texture to OpenGL primitives.
00152   ///
00153   ///   Equivalent to a call to <glEnable> and <glBindTexture> with
00154   ///   the appropriate target.
00155   ///
00156   ///   Note: if the current context is different from the last call to
00157   ///   Enable(), the texture will be uploaded again.
00158   ///
00159   void Enable  ();
00160 
00161   ///
00162   /// Disable --
00163   ///   Stop rendering the texture to OpenGL primitives.
00164   ///   Equivalent to a call to <glDisable> with the appropriate target.
00165   ///
00166   ///   The OpenGL context current when Enable() was called must be current.
00167   ///
00168   void Disable ();
00169 
00170   ///
00171   /// Coords --
00172   ///   Given pixel coordinates <ix> and <iy> in the bitmap,
00173   ///   return in <ox> and <oy> the coordinates to be used in <glTexCoord>.
00174   ///
00175   ///   Note: this is to take ordering and possible padding of the texture 
00176   ///   lines into account, as well as different coordinate conventions
00177   ///   depending on the texture target used (GL_TEXTURE_2D or
00178   ///   GL_TEXTURE_RECTANGLE_EXT).
00179   ///
00180   ///   Can only be called after Upload().
00181   ///
00182   void Coords (GLfloat ix, GLfloat iy, GLfloat &ox, GLfloat &oy);
00183 
00184   ///
00185   /// NormalCoords --
00186   ///   Same as Coords, but with input coordinates normalized to the size 
00187   ///   of the bitmap's region of interest.
00188   ///
00189   ///   Can only be called after Upload().
00190   ///
00191   void NormalCoords (GLfloat ix, GLfloat iy, GLfloat &ox, GLfloat &oy);
00192 
00193   ///
00194   /// Alpha --
00195   ///   Returns the transparency parameter of the bitmap pixel at coordinates
00196   ///   <x>, <y>.
00197   ///   
00198   ///   If <x>, <y> is out of range of the texture, return 0 (fully transparent).
00199   ///   If the texture has no transparency information, return 1 (fully opaque).
00200   ///
00201   ///   Note: The origin of bitmap coordinates is at the top left corner 
00202   ///   of the texture .
00203   ///
00204   ///   Can only be called after Upload().
00205   ///
00206   Float32 Alpha (Float32 x, Float32 y);
00207   
00208   GLuint GLName () { return fName; }
00209 
00210   void Rect (gml_TRect &rect) {
00211     rect.fLeft = 0;
00212     rect.fTop  = 0;
00213     rect.fRight = fRegionWidth;
00214     rect.fBottom = fRegionHeight;
00215   }
00216 
00217 private:
00218   gml_TBitmap*        fBitmap;      ///< the last <bitmap> argument passed to SetBitmap()
00219   gml_TBitmap*        fPrivateCopy; ///< a private copy of the last bitmap passed to SetBitmap()
00220   gml_TBitmap*        fShadow;      ///< equal either to <fBitmap> or <fPrivateCopy>
00221   gml_TRect           fRegion;      ///< the last <roi> argument passed to SetBitmap()
00222   SInt32              fRegionWidth;
00223   SInt32              fRegionHeight;
00224   SInt32              fAlphaIndex;  ///< byte index of the alpha channel in the bitmap's pixels,
00225                                     ///< or (-1) if it has no alpha.
00226   
00227   GLuint              fWidth;       ///< width of the OpenGL texture
00228   GLuint              fHeight;      ///< height of the OpenGL texture
00229   
00230 
00231   GLuint              fName;        ///< OpenGL handle for this texture
00232   gml_TBoolean        fUploaded;    ///< true if the texture has already been uploaded
00233                                     ///< at least once
00234   GLint               fInternal;    ///< Component layout of the texture in VRAM
00235   GLenum              fFormat;      ///< Component layout of the pixel data
00236   GLenum              fType;        ///< Data type of the pixel data
00237   GLenum              fTarget;      ///< Target texture type, GL_TEXTURE_2D or 
00238                                     ///< GL_TEXTURE_RECTANGLE_EXT
00239   GLuint              fFramebuffer; ///< virtual frame buffer user for render-to-texture operations
00240   
00241   GLuint              fDownloadBuffer;
00242   GLuint              fDownloadSize;
00243   gml_TBitmap         fDownloadBitmap;
00244   
00245   
00246   ///
00247   /// CheckEncodingAndSize --
00248   ///   If the texture has already been uploaded with an incompatible bitmap
00249   ///   (different dimensions or encodings), prepare to re-upload it.
00250   ///
00251   void CheckEncodingAndSize (gml_TBitmap *bm, gml_TRect *roi);
00252 
00253   void GLSetupUploadStart ();
00254   void GLSetupUploadEnd ();
00255   void GLUploadTexture ();
00256   void GLCreateTexture ();
00257 
00258   gml_TError DownloadReadPixels   (gml_TBitmap* bitmap, gml_TRect* source, gml_TRect* dest);
00259   gml_TError DownloadGetTexImage  (gml_TBitmap* bitmap, gml_TRect* source, gml_TRect* dest);
00260 };
00261 
00262 #endif /* __GML_GL_TEXTURE__ */
Generated on Tue Jun 12 14:03:27 2007 for gml by Doxygen 1.5.2.