vrshoot
diff libs/assimp/BaseImporter.h @ 0:b2f14e535253
initial commit
author | John Tsiombikas <nuclear@member.fsf.org> |
---|---|
date | Sat, 01 Feb 2014 19:58:19 +0200 |
parents | |
children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/libs/assimp/BaseImporter.h Sat Feb 01 19:58:19 2014 +0200 1.3 @@ -0,0 +1,359 @@ 1.4 +/* 1.5 +Open Asset Import Library (assimp) 1.6 +---------------------------------------------------------------------- 1.7 + 1.8 +Copyright (c) 2006-2012, assimp team 1.9 +All rights reserved. 1.10 + 1.11 +Redistribution and use of this software in source and binary forms, 1.12 +with or without modification, are permitted provided that the 1.13 +following conditions are met: 1.14 + 1.15 +* Redistributions of source code must retain the above 1.16 + copyright notice, this list of conditions and the 1.17 + following disclaimer. 1.18 + 1.19 +* Redistributions in binary form must reproduce the above 1.20 + copyright notice, this list of conditions and the 1.21 + following disclaimer in the documentation and/or other 1.22 + materials provided with the distribution. 1.23 + 1.24 +* Neither the name of the assimp team, nor the names of its 1.25 + contributors may be used to endorse or promote products 1.26 + derived from this software without specific prior 1.27 + written permission of the assimp team. 1.28 + 1.29 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 1.30 +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 1.31 +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 1.32 +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 1.33 +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 1.34 +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 1.35 +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 1.36 +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 1.37 +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 1.38 +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 1.39 +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 1.40 + 1.41 +---------------------------------------------------------------------- 1.42 +*/ 1.43 + 1.44 +/** @file Definition of the base class for all importer worker classes. */ 1.45 +#ifndef INCLUDED_AI_BASEIMPORTER_H 1.46 +#define INCLUDED_AI_BASEIMPORTER_H 1.47 + 1.48 +#include "Exceptional.h" 1.49 + 1.50 +#include <string> 1.51 +#include <map> 1.52 +#include <vector> 1.53 +#include "assimp/types.h" 1.54 + 1.55 +struct aiScene; 1.56 + 1.57 +namespace Assimp { 1.58 + 1.59 +class IOSystem; 1.60 +class Importer; 1.61 +class BaseImporter; 1.62 +class BaseProcess; 1.63 +class SharedPostProcessInfo; 1.64 +class IOStream; 1.65 + 1.66 +// utility to do char4 to uint32 in a portable manner 1.67 +#define AI_MAKE_MAGIC(string) ((uint32_t)((string[0] << 24) + \ 1.68 + (string[1] << 16) + (string[2] << 8) + string[3])) 1.69 + 1.70 +// --------------------------------------------------------------------------- 1.71 +template <typename T> 1.72 +struct ScopeGuard 1.73 +{ 1.74 + ScopeGuard(T* obj) : obj(obj), mdismiss() {} 1.75 + ~ScopeGuard () throw() { 1.76 + if (!mdismiss) { 1.77 + delete obj; 1.78 + } 1.79 + obj = NULL; 1.80 + } 1.81 + 1.82 + T* dismiss() { 1.83 + mdismiss=true; 1.84 + return obj; 1.85 + } 1.86 + 1.87 + operator T*() { 1.88 + return obj; 1.89 + } 1.90 + 1.91 + T* operator -> () { 1.92 + return obj; 1.93 + } 1.94 + 1.95 +private: 1.96 + T* obj; 1.97 + bool mdismiss; 1.98 +}; 1.99 + 1.100 + 1.101 + 1.102 +// --------------------------------------------------------------------------- 1.103 +/** FOR IMPORTER PLUGINS ONLY: The BaseImporter defines a common interface 1.104 + * for all importer worker classes. 1.105 + * 1.106 + * The interface defines two functions: CanRead() is used to check if the 1.107 + * importer can handle the format of the given file. If an implementation of 1.108 + * this function returns true, the importer then calls ReadFile() which 1.109 + * imports the given file. ReadFile is not overridable, it just calls 1.110 + * InternReadFile() and catches any ImportErrorException that might occur. 1.111 + */ 1.112 +class BaseImporter 1.113 +{ 1.114 + friend class Importer; 1.115 + 1.116 +public: 1.117 + 1.118 + /** Constructor to be privately used by #Importer */ 1.119 + BaseImporter(); 1.120 + 1.121 + /** Destructor, private as well */ 1.122 + virtual ~BaseImporter(); 1.123 + 1.124 +public: 1.125 + // ------------------------------------------------------------------- 1.126 + /** Returns whether the class can handle the format of the given file. 1.127 + * 1.128 + * The implementation should be as quick as possible. A check for 1.129 + * the file extension is enough. If no suitable loader is found with 1.130 + * this strategy, CanRead() is called again, the 'checkSig' parameter 1.131 + * set to true this time. Now the implementation is expected to 1.132 + * perform a full check of the file structure, possibly searching the 1.133 + * first bytes of the file for magic identifiers or keywords. 1.134 + * 1.135 + * @param pFile Path and file name of the file to be examined. 1.136 + * @param pIOHandler The IO handler to use for accessing any file. 1.137 + * @param checkSig Set to true if this method is called a second time. 1.138 + * This time, the implementation may take more time to examine the 1.139 + * contents of the file to be loaded for magic bytes, keywords, etc 1.140 + * to be able to load files with unknown/not existent file extensions. 1.141 + * @return true if the class can read this file, false if not. 1.142 + */ 1.143 + virtual bool CanRead( 1.144 + const std::string& pFile, 1.145 + IOSystem* pIOHandler, 1.146 + bool checkSig 1.147 + ) const = 0; 1.148 + 1.149 + // ------------------------------------------------------------------- 1.150 + /** Imports the given file and returns the imported data. 1.151 + * If the import succeeds, ownership of the data is transferred to 1.152 + * the caller. If the import fails, NULL is returned. The function 1.153 + * takes care that any partially constructed data is destroyed 1.154 + * beforehand. 1.155 + * 1.156 + * @param pImp #Importer object hosting this loader. 1.157 + * @param pFile Path of the file to be imported. 1.158 + * @param pIOHandler IO-Handler used to open this and possible other files. 1.159 + * @return The imported data or NULL if failed. If it failed a 1.160 + * human-readable error description can be retrieved by calling 1.161 + * GetErrorText() 1.162 + * 1.163 + * @note This function is not intended to be overridden. Implement 1.164 + * InternReadFile() to do the import. If an exception is thrown somewhere 1.165 + * in InternReadFile(), this function will catch it and transform it into 1.166 + * a suitable response to the caller. 1.167 + */ 1.168 + aiScene* ReadFile( 1.169 + const Importer* pImp, 1.170 + const std::string& pFile, 1.171 + IOSystem* pIOHandler 1.172 + ); 1.173 + 1.174 + // ------------------------------------------------------------------- 1.175 + /** Returns the error description of the last error that occured. 1.176 + * @return A description of the last error that occured. An empty 1.177 + * string if there was no error. 1.178 + */ 1.179 + const std::string& GetErrorText() const { 1.180 + return mErrorText; 1.181 + } 1.182 + 1.183 + // ------------------------------------------------------------------- 1.184 + /** Called prior to ReadFile(). 1.185 + * The function is a request to the importer to update its configuration 1.186 + * basing on the Importer's configuration property list. 1.187 + * @param pImp Importer instance 1.188 + */ 1.189 + virtual void SetupProperties( 1.190 + const Importer* pImp 1.191 + ); 1.192 + 1.193 + 1.194 + // ------------------------------------------------------------------- 1.195 + /** Called by #Importer::GetImporterInfo to get a description of 1.196 + * some loader features. Importers must provide this information. */ 1.197 + virtual const aiImporterDesc* GetInfo() const = 0; 1.198 + 1.199 + 1.200 + 1.201 + // ------------------------------------------------------------------- 1.202 + /** Called by #Importer::GetExtensionList for each loaded importer. 1.203 + * Take the extension list contained in the structure returned by 1.204 + * #GetInfo and insert all file extensions into the given set. 1.205 + * @param extension set to collect file extensions in*/ 1.206 + void GetExtensionList(std::set<std::string>& extensions); 1.207 + 1.208 +protected: 1.209 + 1.210 + // ------------------------------------------------------------------- 1.211 + /** Imports the given file into the given scene structure. The 1.212 + * function is expected to throw an ImportErrorException if there is 1.213 + * an error. If it terminates normally, the data in aiScene is 1.214 + * expected to be correct. Override this function to implement the 1.215 + * actual importing. 1.216 + * <br> 1.217 + * The output scene must meet the following requirements:<br> 1.218 + * <ul> 1.219 + * <li>At least a root node must be there, even if its only purpose 1.220 + * is to reference one mesh.</li> 1.221 + * <li>aiMesh::mPrimitiveTypes may be 0. The types of primitives 1.222 + * in the mesh are determined automatically in this case.</li> 1.223 + * <li>the vertex data is stored in a pseudo-indexed "verbose" format. 1.224 + * In fact this means that every vertex that is referenced by 1.225 + * a face is unique. Or the other way round: a vertex index may 1.226 + * not occur twice in a single aiMesh.</li> 1.227 + * <li>aiAnimation::mDuration may be -1. Assimp determines the length 1.228 + * of the animation automatically in this case as the length of 1.229 + * the longest animation channel.</li> 1.230 + * <li>aiMesh::mBitangents may be NULL if tangents and normals are 1.231 + * given. In this case bitangents are computed as the cross product 1.232 + * between normal and tangent.</li> 1.233 + * <li>There needn't be a material. If none is there a default material 1.234 + * is generated. However, it is recommended practice for loaders 1.235 + * to generate a default material for yourself that matches the 1.236 + * default material setting for the file format better than Assimp's 1.237 + * generic default material. Note that default materials *should* 1.238 + * be named AI_DEFAULT_MATERIAL_NAME if they're just color-shaded 1.239 + * or AI_DEFAULT_TEXTURED_MATERIAL_NAME if they define a (dummy) 1.240 + * texture. </li> 1.241 + * </ul> 1.242 + * If the AI_SCENE_FLAGS_INCOMPLETE-Flag is <b>not</b> set:<ul> 1.243 + * <li> at least one mesh must be there</li> 1.244 + * <li> there may be no meshes with 0 vertices or faces</li> 1.245 + * </ul> 1.246 + * This won't be checked (except by the validation step): Assimp will 1.247 + * crash if one of the conditions is not met! 1.248 + * 1.249 + * @param pFile Path of the file to be imported. 1.250 + * @param pScene The scene object to hold the imported data. 1.251 + * NULL is not a valid parameter. 1.252 + * @param pIOHandler The IO handler to use for any file access. 1.253 + * NULL is not a valid parameter. */ 1.254 + virtual void InternReadFile( 1.255 + const std::string& pFile, 1.256 + aiScene* pScene, 1.257 + IOSystem* pIOHandler 1.258 + ) = 0; 1.259 + 1.260 +public: // static utilities 1.261 + 1.262 + // ------------------------------------------------------------------- 1.263 + /** A utility for CanRead(). 1.264 + * 1.265 + * The function searches the header of a file for a specific token 1.266 + * and returns true if this token is found. This works for text 1.267 + * files only. There is a rudimentary handling of UNICODE files. 1.268 + * The comparison is case independent. 1.269 + * 1.270 + * @param pIOSystem IO System to work with 1.271 + * @param file File name of the file 1.272 + * @param tokens List of tokens to search for 1.273 + * @param numTokens Size of the token array 1.274 + * @param searchBytes Number of bytes to be searched for the tokens. 1.275 + */ 1.276 + static bool SearchFileHeaderForToken( 1.277 + IOSystem* pIOSystem, 1.278 + const std::string& file, 1.279 + const char** tokens, 1.280 + unsigned int numTokens, 1.281 + unsigned int searchBytes = 200, 1.282 + bool tokensSol = false); 1.283 + 1.284 + // ------------------------------------------------------------------- 1.285 + /** @brief Check whether a file has a specific file extension 1.286 + * @param pFile Input file 1.287 + * @param ext0 Extension to check for. Lowercase characters only, no dot! 1.288 + * @param ext1 Optional second extension 1.289 + * @param ext2 Optional third extension 1.290 + * @note Case-insensitive 1.291 + */ 1.292 + static bool SimpleExtensionCheck ( 1.293 + const std::string& pFile, 1.294 + const char* ext0, 1.295 + const char* ext1 = NULL, 1.296 + const char* ext2 = NULL); 1.297 + 1.298 + // ------------------------------------------------------------------- 1.299 + /** @brief Extract file extension from a string 1.300 + * @param pFile Input file 1.301 + * @return Extension without trailing dot, all lowercase 1.302 + */ 1.303 + static std::string GetExtension ( 1.304 + const std::string& pFile); 1.305 + 1.306 + // ------------------------------------------------------------------- 1.307 + /** @brief Check whether a file starts with one or more magic tokens 1.308 + * @param pFile Input file 1.309 + * @param pIOHandler IO system to be used 1.310 + * @param magic n magic tokens 1.311 + * @params num Size of magic 1.312 + * @param offset Offset from file start where tokens are located 1.313 + * @param Size of one token, in bytes. Maximally 16 bytes. 1.314 + * @return true if one of the given tokens was found 1.315 + * 1.316 + * @note For convinence, the check is also performed for the 1.317 + * byte-swapped variant of all tokens (big endian). Only for 1.318 + * tokens of size 2,4. 1.319 + */ 1.320 + static bool CheckMagicToken( 1.321 + IOSystem* pIOHandler, 1.322 + const std::string& pFile, 1.323 + const void* magic, 1.324 + unsigned int num, 1.325 + unsigned int offset = 0, 1.326 + unsigned int size = 4); 1.327 + 1.328 + // ------------------------------------------------------------------- 1.329 + /** An utility for all text file loaders. It converts a file to our 1.330 + * UTF8 character set. Errors are reported, but ignored. 1.331 + * 1.332 + * @param data File buffer to be converted to UTF8 data. The buffer 1.333 + * is resized as appropriate. */ 1.334 + static void ConvertToUTF8( 1.335 + std::vector<char>& data); 1.336 + 1.337 + // ------------------------------------------------------------------- 1.338 + /** Utility for text file loaders which copies the contents of the 1.339 + * file into a memory buffer and converts it to our UTF8 1.340 + * representation. 1.341 + * @param stream Stream to read from. 1.342 + * @param data Output buffer to be resized and filled with the 1.343 + * converted text file data. The buffer is terminated with 1.344 + * a binary 0. */ 1.345 + static void TextFileToBuffer( 1.346 + IOStream* stream, 1.347 + std::vector<char>& data); 1.348 + 1.349 +protected: 1.350 + 1.351 + /** Error description in case there was one. */ 1.352 + std::string mErrorText; 1.353 + 1.354 + /** Currently set progress handler */ 1.355 + ProgressHandler* progress; 1.356 +}; 1.357 + 1.358 + 1.359 + 1.360 +} // end of namespace Assimp 1.361 + 1.362 +#endif // AI_BASEIMPORTER_H_INC