|
| 1 | +/* |
| 2 | +Open Asset Import Library (assimp) |
| 3 | +---------------------------------------------------------------------- |
| 4 | +
|
| 5 | +Copyright (c) 2006-2018, assimp team |
| 6 | +
|
| 7 | +
|
| 8 | +All rights reserved. |
| 9 | +
|
| 10 | +Redistribution and use of this software in source and binary forms, |
| 11 | +with or without modification, are permitted provided that the |
| 12 | +following conditions are met: |
| 13 | +
|
| 14 | +* Redistributions of source code must retain the above |
| 15 | + copyright notice, this list of conditions and the |
| 16 | + following disclaimer. |
| 17 | +
|
| 18 | +* Redistributions in binary form must reproduce the above |
| 19 | + copyright notice, this list of conditions and the |
| 20 | + following disclaimer in the documentation and/or other |
| 21 | + materials provided with the distribution. |
| 22 | +
|
| 23 | +* Neither the name of the assimp team, nor the names of its |
| 24 | + contributors may be used to endorse or promote products |
| 25 | + derived from this software without specific prior |
| 26 | + written permission of the assimp team. |
| 27 | +
|
| 28 | +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 29 | +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 30 | +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 31 | +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 32 | +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 33 | +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 34 | +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 35 | +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 36 | +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 37 | +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 38 | +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 39 | +
|
| 40 | +---------------------------------------------------------------------- |
| 41 | +*/ |
| 42 | + |
| 43 | +/** @file Definition of the base class for all importer worker classes. */ |
| 44 | +#ifndef INCLUDED_AI_BASEIMPORTER_H |
| 45 | +#define INCLUDED_AI_BASEIMPORTER_H |
| 46 | + |
| 47 | +#include "Exceptional.h" |
| 48 | + |
| 49 | +#include <vector> |
| 50 | +#include <set> |
| 51 | +#include <assimp/types.h> |
| 52 | +#include <assimp/ProgressHandler.hpp> |
| 53 | + |
| 54 | +struct aiScene; |
| 55 | +struct aiImporterDesc; |
| 56 | + |
| 57 | +namespace Assimp { |
| 58 | + |
| 59 | +class Importer; |
| 60 | +class IOSystem; |
| 61 | +class BaseProcess; |
| 62 | +class SharedPostProcessInfo; |
| 63 | +class IOStream; |
| 64 | + |
| 65 | +// utility to do char4 to uint32 in a portable manner |
| 66 | +#define AI_MAKE_MAGIC(string) ((uint32_t)((string[0] << 24) + \ |
| 67 | + (string[1] << 16) + (string[2] << 8) + string[3])) |
| 68 | + |
| 69 | + |
| 70 | +// --------------------------------------------------------------------------- |
| 71 | +/** FOR IMPORTER PLUGINS ONLY: The BaseImporter defines a common interface |
| 72 | + * for all importer worker classes. |
| 73 | + * |
| 74 | + * The interface defines two functions: CanRead() is used to check if the |
| 75 | + * importer can handle the format of the given file. If an implementation of |
| 76 | + * this function returns true, the importer then calls ReadFile() which |
| 77 | + * imports the given file. ReadFile is not overridable, it just calls |
| 78 | + * InternReadFile() and catches any ImportErrorException that might occur. |
| 79 | + */ |
| 80 | +class ASSIMP_API BaseImporter |
| 81 | +{ |
| 82 | + friend class Importer; |
| 83 | + |
| 84 | +public: |
| 85 | + |
| 86 | + /** Constructor to be privately used by #Importer */ |
| 87 | + BaseImporter(); |
| 88 | + |
| 89 | + /** Destructor, private as well */ |
| 90 | + virtual ~BaseImporter(); |
| 91 | + |
| 92 | +public: |
| 93 | + // ------------------------------------------------------------------- |
| 94 | + /** Returns whether the class can handle the format of the given file. |
| 95 | + * |
| 96 | + * The implementation should be as quick as possible. A check for |
| 97 | + * the file extension is enough. If no suitable loader is found with |
| 98 | + * this strategy, CanRead() is called again, the 'checkSig' parameter |
| 99 | + * set to true this time. Now the implementation is expected to |
| 100 | + * perform a full check of the file structure, possibly searching the |
| 101 | + * first bytes of the file for magic identifiers or keywords. |
| 102 | + * |
| 103 | + * @param pFile Path and file name of the file to be examined. |
| 104 | + * @param pIOHandler The IO handler to use for accessing any file. |
| 105 | + * @param checkSig Set to true if this method is called a second time. |
| 106 | + * This time, the implementation may take more time to examine the |
| 107 | + * contents of the file to be loaded for magic bytes, keywords, etc |
| 108 | + * to be able to load files with unknown/not existent file extensions. |
| 109 | + * @return true if the class can read this file, false if not. |
| 110 | + */ |
| 111 | + virtual bool CanRead( |
| 112 | + const std::string& pFile, |
| 113 | + IOSystem* pIOHandler, |
| 114 | + bool checkSig |
| 115 | + ) const = 0; |
| 116 | + |
| 117 | + // ------------------------------------------------------------------- |
| 118 | + /** Imports the given file and returns the imported data. |
| 119 | + * If the import succeeds, ownership of the data is transferred to |
| 120 | + * the caller. If the import fails, NULL is returned. The function |
| 121 | + * takes care that any partially constructed data is destroyed |
| 122 | + * beforehand. |
| 123 | + * |
| 124 | + * @param pImp #Importer object hosting this loader. |
| 125 | + * @param pFile Path of the file to be imported. |
| 126 | + * @param pIOHandler IO-Handler used to open this and possible other files. |
| 127 | + * @return The imported data or NULL if failed. If it failed a |
| 128 | + * human-readable error description can be retrieved by calling |
| 129 | + * GetErrorText() |
| 130 | + * |
| 131 | + * @note This function is not intended to be overridden. Implement |
| 132 | + * InternReadFile() to do the import. If an exception is thrown somewhere |
| 133 | + * in InternReadFile(), this function will catch it and transform it into |
| 134 | + * a suitable response to the caller. |
| 135 | + */ |
| 136 | + aiScene* ReadFile( |
| 137 | + const Importer* pImp, |
| 138 | + const std::string& pFile, |
| 139 | + IOSystem* pIOHandler |
| 140 | + ); |
| 141 | + |
| 142 | + // ------------------------------------------------------------------- |
| 143 | + /** Returns the error description of the last error that occurred. |
| 144 | + * @return A description of the last error that occurred. An empty |
| 145 | + * string if there was no error. |
| 146 | + */ |
| 147 | + const std::string& GetErrorText() const { |
| 148 | + return m_ErrorText; |
| 149 | + } |
| 150 | + |
| 151 | + // ------------------------------------------------------------------- |
| 152 | + /** Called prior to ReadFile(). |
| 153 | + * The function is a request to the importer to update its configuration |
| 154 | + * basing on the Importer's configuration property list. |
| 155 | + * @param pImp Importer instance |
| 156 | + */ |
| 157 | + virtual void SetupProperties( |
| 158 | + const Importer* pImp |
| 159 | + ); |
| 160 | + |
| 161 | + // ------------------------------------------------------------------- |
| 162 | + /** Called by #Importer::GetImporterInfo to get a description of |
| 163 | + * some loader features. Importers must provide this information. */ |
| 164 | + virtual const aiImporterDesc* GetInfo() const = 0; |
| 165 | + |
| 166 | + // ------------------------------------------------------------------- |
| 167 | + /** Called by #Importer::GetExtensionList for each loaded importer. |
| 168 | + * Take the extension list contained in the structure returned by |
| 169 | + * #GetInfo and insert all file extensions into the given set. |
| 170 | + * @param extension set to collect file extensions in*/ |
| 171 | + void GetExtensionList(std::set<std::string>& extensions); |
| 172 | + |
| 173 | +protected: |
| 174 | + |
| 175 | + // ------------------------------------------------------------------- |
| 176 | + /** Imports the given file into the given scene structure. The |
| 177 | + * function is expected to throw an ImportErrorException if there is |
| 178 | + * an error. If it terminates normally, the data in aiScene is |
| 179 | + * expected to be correct. Override this function to implement the |
| 180 | + * actual importing. |
| 181 | + * <br> |
| 182 | + * The output scene must meet the following requirements:<br> |
| 183 | + * <ul> |
| 184 | + * <li>At least a root node must be there, even if its only purpose |
| 185 | + * is to reference one mesh.</li> |
| 186 | + * <li>aiMesh::mPrimitiveTypes may be 0. The types of primitives |
| 187 | + * in the mesh are determined automatically in this case.</li> |
| 188 | + * <li>the vertex data is stored in a pseudo-indexed "verbose" format. |
| 189 | + * In fact this means that every vertex that is referenced by |
| 190 | + * a face is unique. Or the other way round: a vertex index may |
| 191 | + * not occur twice in a single aiMesh.</li> |
| 192 | + * <li>aiAnimation::mDuration may be -1. Assimp determines the length |
| 193 | + * of the animation automatically in this case as the length of |
| 194 | + * the longest animation channel.</li> |
| 195 | + * <li>aiMesh::mBitangents may be NULL if tangents and normals are |
| 196 | + * given. In this case bitangents are computed as the cross product |
| 197 | + * between normal and tangent.</li> |
| 198 | + * <li>There needn't be a material. If none is there a default material |
| 199 | + * is generated. However, it is recommended practice for loaders |
| 200 | + * to generate a default material for yourself that matches the |
| 201 | + * default material setting for the file format better than Assimp's |
| 202 | + * generic default material. Note that default materials *should* |
| 203 | + * be named AI_DEFAULT_MATERIAL_NAME if they're just color-shaded |
| 204 | + * or AI_DEFAULT_TEXTURED_MATERIAL_NAME if they define a (dummy) |
| 205 | + * texture. </li> |
| 206 | + * </ul> |
| 207 | + * If the AI_SCENE_FLAGS_INCOMPLETE-Flag is <b>not</b> set:<ul> |
| 208 | + * <li> at least one mesh must be there</li> |
| 209 | + * <li> there may be no meshes with 0 vertices or faces</li> |
| 210 | + * </ul> |
| 211 | + * This won't be checked (except by the validation step): Assimp will |
| 212 | + * crash if one of the conditions is not met! |
| 213 | + * |
| 214 | + * @param pFile Path of the file to be imported. |
| 215 | + * @param pScene The scene object to hold the imported data. |
| 216 | + * NULL is not a valid parameter. |
| 217 | + * @param pIOHandler The IO handler to use for any file access. |
| 218 | + * NULL is not a valid parameter. */ |
| 219 | + virtual void InternReadFile( |
| 220 | + const std::string& pFile, |
| 221 | + aiScene* pScene, |
| 222 | + IOSystem* pIOHandler |
| 223 | + ) = 0; |
| 224 | + |
| 225 | +public: // static utilities |
| 226 | + |
| 227 | + // ------------------------------------------------------------------- |
| 228 | + /** A utility for CanRead(). |
| 229 | + * |
| 230 | + * The function searches the header of a file for a specific token |
| 231 | + * and returns true if this token is found. This works for text |
| 232 | + * files only. There is a rudimentary handling of UNICODE files. |
| 233 | + * The comparison is case independent. |
| 234 | + * |
| 235 | + * @param pIOSystem IO System to work with |
| 236 | + * @param file File name of the file |
| 237 | + * @param tokens List of tokens to search for |
| 238 | + * @param numTokens Size of the token array |
| 239 | + * @param searchBytes Number of bytes to be searched for the tokens. |
| 240 | + */ |
| 241 | + static bool SearchFileHeaderForToken( |
| 242 | + IOSystem* pIOSystem, |
| 243 | + const std::string& file, |
| 244 | + const char** tokens, |
| 245 | + unsigned int numTokens, |
| 246 | + unsigned int searchBytes = 200, |
| 247 | + bool tokensSol = false); |
| 248 | + |
| 249 | + // ------------------------------------------------------------------- |
| 250 | + /** @brief Check whether a file has a specific file extension |
| 251 | + * @param pFile Input file |
| 252 | + * @param ext0 Extension to check for. Lowercase characters only, no dot! |
| 253 | + * @param ext1 Optional second extension |
| 254 | + * @param ext2 Optional third extension |
| 255 | + * @note Case-insensitive |
| 256 | + */ |
| 257 | + static bool SimpleExtensionCheck ( |
| 258 | + const std::string& pFile, |
| 259 | + const char* ext0, |
| 260 | + const char* ext1 = NULL, |
| 261 | + const char* ext2 = NULL); |
| 262 | + |
| 263 | + // ------------------------------------------------------------------- |
| 264 | + /** @brief Extract file extension from a string |
| 265 | + * @param pFile Input file |
| 266 | + * @return Extension without trailing dot, all lowercase |
| 267 | + */ |
| 268 | + static std::string GetExtension ( |
| 269 | + const std::string& pFile); |
| 270 | + |
| 271 | + // ------------------------------------------------------------------- |
| 272 | + /** @brief Check whether a file starts with one or more magic tokens |
| 273 | + * @param pFile Input file |
| 274 | + * @param pIOHandler IO system to be used |
| 275 | + * @param magic n magic tokens |
| 276 | + * @params num Size of magic |
| 277 | + * @param offset Offset from file start where tokens are located |
| 278 | + * @param Size of one token, in bytes. Maximally 16 bytes. |
| 279 | + * @return true if one of the given tokens was found |
| 280 | + * |
| 281 | + * @note For convenience, the check is also performed for the |
| 282 | + * byte-swapped variant of all tokens (big endian). Only for |
| 283 | + * tokens of size 2,4. |
| 284 | + */ |
| 285 | + static bool CheckMagicToken( |
| 286 | + IOSystem* pIOHandler, |
| 287 | + const std::string& pFile, |
| 288 | + const void* magic, |
| 289 | + unsigned int num, |
| 290 | + unsigned int offset = 0, |
| 291 | + unsigned int size = 4); |
| 292 | + |
| 293 | + // ------------------------------------------------------------------- |
| 294 | + /** An utility for all text file loaders. It converts a file to our |
| 295 | + * UTF8 character set. Errors are reported, but ignored. |
| 296 | + * |
| 297 | + * @param data File buffer to be converted to UTF8 data. The buffer |
| 298 | + * is resized as appropriate. */ |
| 299 | + static void ConvertToUTF8( |
| 300 | + std::vector<char>& data); |
| 301 | + |
| 302 | + // ------------------------------------------------------------------- |
| 303 | + /** An utility for all text file loaders. It converts a file from our |
| 304 | + * UTF8 character set back to ISO-8859-1. Errors are reported, but ignored. |
| 305 | + * |
| 306 | + * @param data File buffer to be converted from UTF8 to ISO-8859-1. The buffer |
| 307 | + * is resized as appropriate. */ |
| 308 | + static void ConvertUTF8toISO8859_1( |
| 309 | + std::string& data); |
| 310 | + |
| 311 | + // ------------------------------------------------------------------- |
| 312 | + /// @brief Enum to define, if empty files are ok or not. |
| 313 | + enum TextFileMode { |
| 314 | + ALLOW_EMPTY, |
| 315 | + FORBID_EMPTY |
| 316 | + }; |
| 317 | + |
| 318 | + // ------------------------------------------------------------------- |
| 319 | + /** Utility for text file loaders which copies the contents of the |
| 320 | + * file into a memory buffer and converts it to our UTF8 |
| 321 | + * representation. |
| 322 | + * @param stream Stream to read from. |
| 323 | + * @param data Output buffer to be resized and filled with the |
| 324 | + * converted text file data. The buffer is terminated with |
| 325 | + * a binary 0. |
| 326 | + * @param mode Whether it is OK to load empty text files. */ |
| 327 | + static void TextFileToBuffer( |
| 328 | + IOStream* stream, |
| 329 | + std::vector<char>& data, |
| 330 | + TextFileMode mode = FORBID_EMPTY); |
| 331 | + |
| 332 | + // ------------------------------------------------------------------- |
| 333 | + /** Utility function to move a std::vector into a aiScene array |
| 334 | + * @param vec The vector to be moved |
| 335 | + * @param out The output pointer to the allocated array. |
| 336 | + * @param numOut The output count of elements copied. */ |
| 337 | + template<typename T> |
| 338 | + AI_FORCE_INLINE |
| 339 | + static void CopyVector( |
| 340 | + std::vector<T>& vec, |
| 341 | + T*& out, |
| 342 | + unsigned int& outLength) |
| 343 | + { |
| 344 | + outLength = unsigned(vec.size()); |
| 345 | + if (outLength) { |
| 346 | + out = new T[outLength]; |
| 347 | + std::swap_ranges(vec.begin(), vec.end(), out); |
| 348 | + } |
| 349 | + } |
| 350 | + |
| 351 | +protected: |
| 352 | + /// Error description in case there was one. |
| 353 | + std::string m_ErrorText; |
| 354 | + /// Currently set progress handler. |
| 355 | + ProgressHandler* m_progress; |
| 356 | +}; |
| 357 | + |
| 358 | + |
| 359 | + |
| 360 | +} // end of namespace Assimp |
| 361 | + |
| 362 | +#endif // AI_BASEIMPORTER_H_INC |
0 commit comments