Pyrogenesis  trunk
TextureConverter.h
Go to the documentation of this file.
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"
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  */
64 {
65 public:
66  enum EFormat
67  {
74  };
75 
76  enum EMipmap
77  {
81  };
82 
84  {
88  };
89 
90  enum EAlpha
91  {
96  };
97 
98  enum EFilter
99  {
104  };
105 
106  /**
107  * Texture conversion settings.
108  */
109  struct Settings
110  {
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 
128  float kaiserWidth;
129  float kaiserAlpha;
131  };
132 
133  /**
134  * Representation of <File> line from settings XML file.
135  */
136  struct Match
137  {
138  std::wstring pattern;
140  };
141 
142  /**
143  * Representation of settings XML file.
144  */
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  */
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 
206 
209  SDL_sem* m_WorkerSem;
210 
211  struct ConversionRequest;
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
void * pthread_mutex_t
Definition: wpthread.h:82
Definition: TextureConverter.h:72
Definition: TextureConverter.h:93
bool Poll(CTexturePtr &texture, VfsPath &dest, bool &ok)
Returns the result of a successful ConvertTexture call.
Definition: TextureConverter.cpp:481
std::deque< shared_ptr< ConversionResult > > m_ResultQueue
Definition: TextureConverter.h:215
std::wstring pattern
Definition: TextureConverter.h:138
Definition: TextureConverter.h:94
EFilter
Definition: TextureConverter.h:98
Definition: TextureConverter.h:103
Definition: TextureConverter.h:101
Definition: TextureConverter.h:73
Definition: TextureConverter.h:80
PIVFS m_VFS
Definition: TextureConverter.h:204
shared_ptr< IVFS > PIVFS
Definition: vfs.h:226
SettingsFile * LoadSettings(const VfsPath &path) const
Load a texture conversion settings XML file.
Definition: TextureConverter.cpp:96
float kaiserStretch
Definition: TextureConverter.h:130
Texture conversion settings.
Definition: TextureConverter.h:109
bool m_HighQuality
Definition: TextureConverter.h:205
std::vector< Match > patterns
Definition: TextureConverter.h:147
pthread_mutex_t m_WorkerMutex
Definition: TextureConverter.h:208
void Hash(MD5 &hash)
Append this object&#39;s state to the given hash.
Definition: TextureConverter.cpp:84
Settings()
Definition: TextureConverter.h:111
static void * RunThread(void *data)
Definition: TextureConverter.cpp:540
Definition: TextureConverter.h:87
Settings settings
Definition: TextureConverter.h:139
Definition: TextureConverter.h:100
SDL_sem * m_WorkerSem
Definition: TextureConverter.h:209
EFormat format
Definition: TextureConverter.h:123
Definition: TextureConverter.h:85
Representation of <File> line from settings XML file.
Definition: TextureConverter.h:136
Definition: TextureConverter.h:71
MD5 hashing algorithm.
Definition: MD5.h:27
Definition: path.h:77
Definition: TextureConverter.h:70
Definition: TextureConverter.h:92
pthread_t m_WorkerThread
Definition: TextureConverter.h:207
ENormalMap
Definition: TextureConverter.h:83
Definition: TextureConverter.h:78
Representation of settings XML file.
Definition: TextureConverter.h:145
float kaiserAlpha
Definition: TextureConverter.h:129
bool IsBusy()
Returns whether there is currently a queued request from ConvertTexture().
Definition: TextureConverter.cpp:531
EFilter filter
Definition: TextureConverter.h:127
Definition: TextureConverter.h:86
std::shared_ptr< CTexture > CTexturePtr
Definition: Texture.h:22
EFormat
Definition: TextureConverter.h:66
uintptr_t pthread_t
Definition: wpthread.h:63
float kaiserWidth
Definition: TextureConverter.h:128
EAlpha
Definition: TextureConverter.h:90
Definition: TextureConverter.h:102
Texture conversion helper class.
Definition: TextureConverter.h:63
bool m_Shutdown
Definition: TextureConverter.h:216
Result from worker thread.
Definition: TextureConverter.cpp:74
~CTextureConverter()
Destroy texture converter and wait to shut down worker thread.
Definition: TextureConverter.cpp:305
EAlpha alpha
Definition: TextureConverter.h:126
EMipmap mipmap
Definition: TextureConverter.h:124
Definition: vfs_util.cpp:39
ENormalMap normal
Definition: TextureConverter.h:125
Definition: TextureConverter.h:69
Definition: TextureConverter.h:79
Request for worker thread to process.
Definition: TextureConverter.cpp:60
Definition: TextureConverter.h:95
std::deque< shared_ptr< ConversionRequest > > m_RequestQueue
Definition: TextureConverter.h:212
bool ConvertTexture(const CTexturePtr &texture, const VfsPath &src, const VfsPath &dest, const Settings &settings)
Begin converting a texture, using the given settings.
Definition: TextureConverter.cpp:323
Settings ComputeSettings(const std::wstring &filename, const std::vector< SettingsFile * > &settingsFiles) const
Match a sequence of settings files against a given texture filename, and return the resulting setting...
Definition: TextureConverter.cpp:226
Definition: TextureConverter.h:68
CTextureConverter(PIVFS vfs, bool highQuality)
Construct texture converter, for use with files in the given vfs.
Definition: TextureConverter.cpp:278
EMipmap
Definition: TextureConverter.h:76