Pyrogenesis trunk
TextureConverter.h
Go to the documentation of this file.
1/* Copyright (C) 2023 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/config2.h"
22#include "lib/file/vfs/vfs.h"
23
24#include "TextureManager.h"
25
26#if CONFIG2_NVTT
27#include "ps/Future.h"
28
29#include <memory>
30#include <queue>
31#endif
32
33class MD5;
34
35/**
36 * Texture conversion helper class.
37 * Provides an asynchronous API to convert input image files into compressed DDS,
38 * given various conversion settings.
39 * (The (potentially very slow) compression is a performed asynchronously, so
40 * the game can remain responsive).
41 * Also provides an API to load conversion settings from XML files.
42 *
43 * XML files are of the form:
44 * @code
45 * <Textures>
46 * <File pattern="*" format="dxt5" mipmap="false" alpha="transparency"/>
47 * <File pattern="button_wood.*" format="rgba"/>
48 * </Entity>
49 * @endcode
50 *
51 * 'pattern' is a wildcard expression, matching on filenames.
52 * All other attributes are optional. Later elements override attributes from
53 * earlier elements.
54 *
55 * 'format' is 'dxt1', 'dxt3', 'dxt5' or 'rgba'.
56 *
57 * 'mipmap' is 'true' or 'false'.
58 *
59 * 'normal' is 'true' or 'false'.
60 *
61 * 'alpha' is 'transparency' or 'player' (it determines whether the color value of
62 * 0-alpha pixels is significant or not).
63 *
64 * 'filter' is 'box', 'triangle' or 'kaiser'.
65 *
66 * 'kaiserwidth', 'kaiseralpha', 'kaiserstretch' are floats
67 * (see http://code.google.com/p/nvidia-texture-tools/wiki/ApiDocumentation#Mipmap_Generation)
68 */
70{
71public:
73 {
80 };
81
83 {
87 };
88
90 {
94 };
95
96 enum EAlpha
97 {
102 };
103
105 {
110 };
111
112 /**
113 * Texture conversion settings.
114 */
115 struct Settings
116 {
120 kaiserWidth(-1.f), kaiserAlpha(-1.f), kaiserStretch(-1.f)
121 {
122 }
123
124 /**
125 * Append this object's state to the given hash.
126 */
127 void Hash(MD5& hash);
128
137 };
138
139 /**
140 * Representation of <File> line from settings XML file.
141 */
142 struct Match
143 {
144 std::wstring pattern;
146 };
147
148 /**
149 * Representation of settings XML file.
150 */
152 {
153 std::vector<Match> patterns;
154 };
155
156 /**
157 * Construct texture converter, for use with files in the given vfs.
158 */
159 CTextureConverter(PIVFS vfs, bool highQuality);
160
161 /**
162 * The destructor does wait for already started tasks. This might take a
163 * long time (maybe seconds).
164 */
166
167 /**
168 * Load a texture conversion settings XML file.
169 * Returns NULL on failure.
170 */
171 SettingsFile* LoadSettings(const VfsPath& path) const;
172
173 /**
174 * Match a sequence of settings files against a given texture filename,
175 * and return the resulting settings.
176 * Later entries in settingsFiles override earlier entries.
177 */
178 Settings ComputeSettings(const std::wstring& filename, const std::vector<SettingsFile*>& settingsFiles) const;
179
180 /**
181 * Begin converting a texture, using the given settings.
182 * This will load src and return false on failure.
183 * Otherwise it will return true and start an asynchronous conversion request,
184 * whose result will be returned from Poll() (with the texture and dest passed
185 * into this function).
186 */
187 bool ConvertTexture(const CTexturePtr& texture, const VfsPath& src, const VfsPath& dest, const Settings& settings);
188
189 /**
190 * Returns the result of a successful ConvertTexture call.
191 * If no result is available yet, returns false.
192 * Otherwise, if the conversion succeeded, it sets ok to true and sets
193 * texture and dest to the corresponding values passed into ConvertTexture(),
194 * then returns true.
195 * If the conversion failed, it sets ok to false and doesn't touch the other arguments,
196 * then returns true.
197 */
198 bool Poll(CTexturePtr& texture, VfsPath& dest, bool& ok);
199
200 /**
201 * The TextureConverter shouldn't utilize the CPU/Memory fully, so no
202 * conversion should be started when a call to @p IsBusy returns true.
203 */
204 bool IsBusy() const;
205
206private:
209
210#if CONFIG2_NVTT
211 struct ConversionResult;
212
213 std::queue<Future<std::unique_ptr<ConversionResult>>> m_ResultQueue;
214#endif
215};
216
217#endif // INCLUDED_TEXTURECONVERTER
Texture conversion helper class.
Definition: TextureConverter.h:70
bool IsBusy() const
The TextureConverter shouldn't utilize the CPU/Memory fully, so no conversion should be started when ...
Definition: TextureConverter.cpp:530
CTextureConverter(PIVFS vfs, bool highQuality)
Construct texture converter, for use with files in the given vfs.
Definition: TextureConverter.cpp:304
ENormalMap
Definition: TextureConverter.h:90
@ NORMAL_FALSE
Definition: TextureConverter.h:93
@ NORMAL_UNSPECIFIED
Definition: TextureConverter.h:91
@ NORMAL_TRUE
Definition: TextureConverter.h:92
EFormat
Definition: TextureConverter.h:73
@ FMT_DXT3
Definition: TextureConverter.h:76
@ FMT_RGBA
Definition: TextureConverter.h:78
@ FMT_DXT1
Definition: TextureConverter.h:75
@ FMT_ALPHA
Definition: TextureConverter.h:79
@ FMT_UNSPECIFIED
Definition: TextureConverter.h:74
@ FMT_DXT5
Definition: TextureConverter.h:77
std::queue< Future< std::unique_ptr< ConversionResult > > > m_ResultQueue
Definition: TextureConverter.h:213
~CTextureConverter()
The destructor does wait for already started tasks.
EMipmap
Definition: TextureConverter.h:83
@ MIP_TRUE
Definition: TextureConverter.h:85
@ MIP_UNSPECIFIED
Definition: TextureConverter.h:84
@ MIP_FALSE
Definition: TextureConverter.h:86
SettingsFile * LoadSettings(const VfsPath &path) const
Load a texture conversion settings XML file.
Definition: TextureConverter.cpp:122
EAlpha
Definition: TextureConverter.h:97
@ ALPHA_PLAYER
Definition: TextureConverter.h:100
@ ALPHA_UNSPECIFIED
Definition: TextureConverter.h:98
@ ALPHA_TRANSPARENCY
Definition: TextureConverter.h:101
@ ALPHA_NONE
Definition: TextureConverter.h:99
EFilter
Definition: TextureConverter.h:105
@ FILTER_UNSPECIFIED
Definition: TextureConverter.h:106
@ FILTER_BOX
Definition: TextureConverter.h:107
@ FILTER_KAISER
Definition: TextureConverter.h:109
@ FILTER_TRIANGLE
Definition: TextureConverter.h:108
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:252
bool m_HighQuality
Definition: TextureConverter.h:208
PIVFS m_VFS
Definition: TextureConverter.h:207
bool Poll(CTexturePtr &texture, VfsPath &dest, bool &ok)
Returns the result of a successful ConvertTexture call.
Definition: TextureConverter.cpp:488
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:316
MD5 hashing algorithm.
Definition: MD5.h:28
Definition: path.h:80
std::shared_ptr< CTexture > CTexturePtr
Definition: Texture.h:23
Definition: vfs_util.cpp:39
Response from the asynchronous task.
Definition: TextureConverter.cpp:101
Representation of <File> line from settings XML file.
Definition: TextureConverter.h:143
Settings settings
Definition: TextureConverter.h:145
std::wstring pattern
Definition: TextureConverter.h:144
Representation of settings XML file.
Definition: TextureConverter.h:152
std::vector< Match > patterns
Definition: TextureConverter.h:153
Texture conversion settings.
Definition: TextureConverter.h:116
EFilter filter
Definition: TextureConverter.h:133
EFormat format
Definition: TextureConverter.h:129
EAlpha alpha
Definition: TextureConverter.h:132
ENormalMap normal
Definition: TextureConverter.h:131
EMipmap mipmap
Definition: TextureConverter.h:130
float kaiserAlpha
Definition: TextureConverter.h:135
void Hash(MD5 &hash)
Append this object's state to the given hash.
Definition: TextureConverter.cpp:110
Settings()
Definition: TextureConverter.h:117
float kaiserStretch
Definition: TextureConverter.h:136
float kaiserWidth
Definition: TextureConverter.h:134
std::shared_ptr< IVFS > PIVFS
Definition: vfs.h:220