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