Torque3D Documentation / _generateds / gfxTextureObject.h

gfxTextureObject.h

Engine/source/gfx/gfxTextureObject.h

More...

Classes:

class

Contains information on a locked region of a texture.

Detailed Description

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _GFXTEXTUREOBJECT_H_
 25#define _GFXTEXTUREOBJECT_H_
 26
 27#ifndef _REFBASE_H_
 28#include "core/util/refBase.h"
 29#endif
 30#ifndef _MPOINT3_H_
 31#include "math/mPoint3.h"
 32#endif
 33#ifndef _GFXENUMS_H_
 34#include "gfx/gfxEnums.h"
 35#endif
 36#ifndef _GFXTEXTUREPROFILE_H_
 37#include "gfx/gfxTextureProfile.h"
 38#endif
 39#ifndef _GFXRESOURCE_H_
 40#include "gfx/gfxResource.h"
 41#endif
 42
 43class Point2I;
 44class GFXDevice;
 45class GFXTextureProfile;
 46class GBitmap;
 47struct DDSFile;
 48class RectI;
 49
 50/// Contains information on a locked region of a texture.
 51///
 52/// In general, to access a given pixel in a locked rectangle, use this
 53/// equation:
 54///
 55/// @code
 56///     U8 *pixelAtXY = bits + x * pitch + y * pixelSizeInBytes;
 57/// @endcode
 58///
 59/// @note D3DLOCKED_RECT and this structure match up. If you change this
 60///       assumption, be sure to revisit the D3D GFX implementation.
 61///
 62/// @see GFXTextureObject::lock() 
 63struct GFXLockedRect
 64{
 65   /// Pitch of the lock. This is the spacing in bytes of the start
 66   /// of each row of the locked region.
 67   S32 pitch;
 68
 69   /// Pointer to the start of locked rectangle.
 70   U8* bits;
 71};
 72
 73
 74class GFXTextureObject : public StrongRefBase, public GFXResource
 75{
 76public:
 77
 78   #ifdef TORQUE_DEBUG
 79      // In debug builds we provide a TOC leak tracking system.
 80      static U32 smActiveTOCount;
 81      static GFXTextureObject *smHead;
 82      static U32 dumpActiveTOs();
 83
 84      String            mDebugCreationPath;
 85      String            mDebugDescription;   
 86      GFXTextureObject *mDebugNext;
 87      GFXTextureObject *mDebugPrev;
 88   #endif
 89
 90   /// The path to the texture file if the
 91   /// content was loaded from a resource.
 92   String mPath;
 93
 94   bool mDead;
 95
 96   /// The device this texture belongs to.
 97   GFXDevice *mDevice;   
 98
 99   /// The next texture in the linked list.
100   /// @see GFXTextureManager::mListHead
101   GFXTextureObject *mNext;
102
103   /// The previous texture in the linked list.
104   /// @see GFXTextureManager::mListHead
105   GFXTextureObject *mPrev;
106
107   /// The siblings in the cache hash table.
108   /// @see GFXTextureManager::mHashTable
109   GFXTextureObject *mHashNext;
110
111   /// This is the file name or other unique string used 
112   /// to hash this texture object.
113   String mTextureLookupName;
114
115   /// The time at which all references to this
116   /// texture were removed.
117   U32 mDeleteTime;
118
119   Point3I  mBitmapSize;
120   Point3I  mTextureSize;
121   U32      mMipLevels;
122
123   // TODO: This looks unused in the engine... not even sure
124   // what it means.  We should investigate and remove it.
125   S32      mAntialiasLevel;
126
127   bool     mHasTransparency;
128
129   // These two should be removed, and replaced by a reference to a resource
130   // object, or data buffer. Something more generic. -patw
131   GBitmap           *mBitmap;   ///< GBitmap we are backed by.
132   DDSFile           *mDDS;      ///< DDSFile we're backed by.
133      
134   U32 getFormatByteSize() const { return GFXFormat_getByteSize( mFormat ); }
135
136   GFXTextureProfile *mProfile;
137   GFXFormat          mFormat;
138
139
140   GFXTextureObject(GFXDevice * aDevice, GFXTextureProfile *profile);
141   virtual ~GFXTextureObject();
142
143   GBitmap *getBitmap();
144   DDSFile *getDDS();
145   U32 getWidth() const { return mTextureSize.x; }
146   U32 getHeight() const { return mTextureSize.y; }
147   const Point3I& getSize() const { return mTextureSize; }
148   U32 getDepth() const { return mTextureSize.z; }
149   U32 getMipLevels() const { return mMipLevels; }
150   U32 getBitmapWidth() const { return mBitmapSize.x; }
151   U32 getBitmapHeight() const { return mBitmapSize.y; }
152   U32 getBitmapDepth() const { return mBitmapSize.z; }
153   GFXFormat getFormat() const { return mFormat; }
154
155   /// Returns true if this texture is a render target.
156   bool isRenderTarget() const { return mProfile->isRenderTarget(); }
157
158   /// Returns the file path to the texture if
159   /// it was loaded from disk.
160   const String& getPath() const { return mPath; }
161
162   virtual F32 getMaxUCoord() const;
163   virtual F32 getMaxVCoord() const;
164
165   /// Returns the estimated video memory usage 
166   /// in bytes including mipmaps.
167   U32 getEstimatedSizeInBytes() const;
168
169   /// Acquire a lock on part of the texture. The GFXLockedRect returned
170   /// is managed by the GFXTextureObject and does not need to be freed.
171   virtual GFXLockedRect * lock( U32 mipLevel = 0, RectI *inRect = NULL ) = 0;
172
173   /// Releases a lock previously acquired. Note that the mipLevel parameter
174   /// must match the corresponding lock!
175   virtual void unlock( U32 mipLevel = 0) = 0;
176
177   // copy the texture data into the specified bitmap.  
178   //   - this texture object must be a render target.  the function will assert if this is not the case.
179   //   - you must have called allocateBitmap() on the input bitmap first.  the bitmap should have the 
180   //   same dimensions as this texture.  the bitmap format can be RGB or RGBA (in the latter case
181   //   the alpha values from the texture are copied too)
182   //   - returns true if successful, false otherwise
183   //   - this process is not fast.
184   virtual bool copyToBmp(GBitmap* bmp) = 0;
185
186   #ifdef TORQUE_DEBUG
187
188   // It is important for any derived objects to define this method
189   // and also call 'kill' from their destructors.  If you fail to
190   // do either, you will get a pure virtual function call crash
191   // in debug mode.  This is a precaution to make sure you don't
192   // forget to add 'kill' to your destructor.
193   virtual void pureVirtualCrash() = 0;
194
195   #endif
196
197   virtual void kill();
198
199   /// Debug helper function for writing the texture to disk.
200   bool dumpToDisk( const String &bmType, const String &path );
201
202   // GFXResource interface
203   /// The resource should put a description of itself (number of vertices, size/width of texture, etc.) in buffer
204   virtual const String describeSelf() const;
205
206   // StrongRefBase
207   virtual void destroySelf();
208};
209
210//-----------------------------------------------------------------------------
211
212inline GBitmap *GFXTextureObject::getBitmap()
213{
214   AssertFatal( mProfile->doStoreBitmap(), avar("GFXTextureObject::getBitmap - Cannot access bitmap for a '%s' texture.", mProfile->getName().c_str()) );
215
216   return mBitmap;
217}
218
219inline DDSFile *GFXTextureObject::getDDS()
220{
221   AssertFatal( mProfile->doStoreBitmap(), avar("GFXTextureObject::getDDS - Cannot access bitmap for a '%s' texture.", mProfile->getName().c_str()) );
222
223   return mDDS;
224}
225
226#endif // _GFXTEXTUREOBJECT_H_
227