source/graphics/TextureConverter.h

   1 /* Copyright (C) 2012 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef INCLUDED_TEXTURECONVERTER
  19 #define INCLUDED_TEXTURECONVERTER
  20
  21 #include "lib/file/vfs/vfs.h"
  22 #include "lib/posix/posix_pthread.h"
  23 #include "lib/external_libraries/libsdl.h"
  24
  25 #include "TextureManager.h"
  26
  27 class MD5;
  28
  29 /**
  30  * Texture conversion helper class.
  31  * Provides an asynchronous API to convert input image files into compressed DDS,
  32  * given various conversion settings.
  33  * (The (potentially very slow) compression is a performed in a background thread,
  34  * so the game can remain responsive).
  35  * Also provides an API to load conversion settings from XML files.
  36  *
  37  * XML files are of the form:
  38  * @code
  39  * <Textures>
  40  *   <File pattern="*" format="dxt5" mipmap="false" alpha="transparency"/>
  41  *   <File pattern="button_wood.*" format="rgba"/>
  42  * </Entity>
  43  * @endcode
  44  *
  45  * 'pattern' is a wildcard expression, matching on filenames.
  46  * All other attributes are optional. Later elements override attributes from
  47  * earlier elements.
  48  *
  49  * 'format' is 'dxt1', 'dxt3', 'dxt5' or 'rgba'.
  50  *
  51  * 'mipmap' is 'true' or 'false'.
  52  *
  53  * 'normal' is 'true' or 'false'.
  54  *
  55  * 'alpha' is 'transparency' or 'player' (it determines whether the color value of
  56  * 0-alpha pixels is significant or not).
  57  *
  58  * 'filter' is 'box', 'triangle' or 'kaiser'.
  59  *
  60  * 'kaiserwidth', 'kaiseralpha', 'kaiserstretch' are floats
  61  * (see http://code.google.com/p/nvidia-texture-tools/wiki/ApiDocumentation#Mipmap_Generation)
  62  */
  63 class CTextureConverter
  64 {
  65 public:
  66         enum EFormat
  67         {
  68                 FMT_UNSPECIFIED,
  69                 FMT_DXT1,
  70                 FMT_DXT3,
  71                 FMT_DXT5,
  72                 FMT_RGBA,
  73                 FMT_ALPHA
  74         };
  75
  76         enum EMipmap
  77         {
  78                 MIP_UNSPECIFIED,
  79                 MIP_TRUE,
  80                 MIP_FALSE
  81         };
  82
  83         enum ENormalMap
  84         {
  85                 NORMAL_UNSPECIFIED,
  86                 NORMAL_TRUE,
  87                 NORMAL_FALSE
  88         };
  89
  90         enum EAlpha
  91         {
  92                 ALPHA_UNSPECIFIED,
  93                 ALPHA_NONE,
  94                 ALPHA_PLAYER,
  95                 ALPHA_TRANSPARENCY
  96         };
  97
  98         enum EFilter
  99         {
 100                 FILTER_UNSPECIFIED,
 101                 FILTER_BOX,
 102                 FILTER_TRIANGLE,
 103                 FILTER_KAISER
 104         };
 105
 106         /**
 107          * Texture conversion settings.
 108          */
 109         struct Settings
 110         {
 111                 Settings() :
 112                         format(FMT_UNSPECIFIED), mipmap(MIP_UNSPECIFIED), normal(NORMAL_UNSPECIFIED),
 113                         alpha(ALPHA_UNSPECIFIED), filter(FILTER_UNSPECIFIED),
 114                         kaiserWidth(-1.f), kaiserAlpha(-1.f), kaiserStretch(-1.f)
 115                 {
 116                 }
 117
 118                 /**
 119                  * Append this object's state to the given hash.
 120                  */
 121                 void Hash(MD5& hash);
 122
 123                 EFormat format;
 124                 EMipmap mipmap;
 125                 ENormalMap normal;
 126                 EAlpha alpha;
 127                 EFilter filter;
 128                 float kaiserWidth;
 129                 float kaiserAlpha;
 130                 float kaiserStretch;
 131         };
 132
 133         /**
 134          * Representation of \<File\> line from settings XML file.
 135          */
 136         struct Match
 137         {
 138                 std::wstring pattern;
 139                 Settings settings;
 140         };
 141
 142         /**
 143          * Representation of settings XML file.
 144          */
 145         struct SettingsFile
 146         {
 147                 std::vector<Match> patterns;
 148         };
 149
 150         /**
 151          * Construct texture converter, for use with files in the given vfs.
 152          */
 153         CTextureConverter(PIVFS vfs, bool highQuality);
 154
 155         /**
 156          * Destroy texture converter and wait to shut down worker thread.
 157          * This might take a long time (maybe seconds) if the worker is busy
 158          * processing a texture.
 159          */
 160         ~CTextureConverter();
 161
 162         /**
 163          * Load a texture conversion settings XML file.
 164          * Returns NULL on failure.
 165          */
 166         SettingsFile* LoadSettings(const VfsPath& path) const;
 167
 168         /**
 169          * Match a sequence of settings files against a given texture filename,
 170          * and return the resulting settings.
 171          * Later entries in settingsFiles override earlier entries.
 172          */
 173         Settings ComputeSettings(const std::wstring& filename, const std::vector<SettingsFile*>& settingsFiles) const;
 174
 175         /**
 176          * Begin converting a texture, using the given settings.
 177          * This will load src and return false on failure.
 178          * Otherwise it will return true and start an asynchronous conversion request,
 179          * whose result will be returned from Poll() (with the texture and dest passed
 180          * into this function).
 181          */
 182         bool ConvertTexture(const CTexturePtr& texture, const VfsPath& src, const VfsPath& dest, const Settings& settings);
 183
 184         /**
 185          * Returns the result of a successful ConvertTexture call.
 186          * If no result is available yet, returns false.
 187          * Otherwise, if the conversion succeeded, it sets ok to true and sets
 188          * texture and dest to the corresponding values passed into ConvertTexture(),
 189          * then returns true.
 190          * If the conversion failed, it sets ok to false and doesn't touch the other arguments,
 191          * then returns true.
 192          */
 193         bool Poll(CTexturePtr& texture, VfsPath& dest, bool& ok);
 194
 195         /**
 196          * Returns whether there is currently a queued request from ConvertTexture().
 197          * (Note this may return false while the worker thread is still converting the last texture.)
 198          */
 199         bool IsBusy();
 200
 201 private:
 202         static void* RunThread(void* data);
 203
 204         PIVFS m_VFS;
 205         bool m_HighQuality;
 206
 207         pthread_t m_WorkerThread;
 208         pthread_mutex_t m_WorkerMutex;
 209         SDL_sem* m_WorkerSem;
 210
 211         struct ConversionRequest;
 212         struct ConversionResult;
 213
 214         std::deque<shared_ptr<ConversionRequest> > m_RequestQueue; // protected by m_WorkerMutex
 215         std::deque<shared_ptr<ConversionResult> > m_ResultQueue; // protected by m_WorkerMutex
 216         bool m_Shutdown; // protected by m_WorkerMutex
 217 };
 218
 219 #endif // INCLUDED_TEXTURECONVERTER