1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libs/assimp/assimp/Importer.hpp	Sat Feb 01 19:58:19 2014 +0200
     1.3 @@ -0,0 +1,643 @@
     1.4 +/*
     1.5 +---------------------------------------------------------------------------
     1.6 +Open Asset Import Library (assimp)
     1.7 +---------------------------------------------------------------------------
     1.8 +
     1.9 +Copyright (c) 2006-2012, assimp team
    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 following 
    1.15 +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 +/** @file  assimp.hpp
    1.46 + *  @brief Defines the C++-API to the Open Asset Import Library.
    1.47 + */
    1.48 +#ifndef INCLUDED_AI_ASSIMP_HPP
    1.49 +#define INCLUDED_AI_ASSIMP_HPP
    1.50 +
    1.51 +#ifndef __cplusplus
    1.52 +#	error This header requires C++ to be used. Use assimp.h for plain C. 
    1.53 +#endif
    1.54 +
    1.55 +// Public ASSIMP data structures
    1.56 +#include "types.h"
    1.57 +#include "config.h"
    1.58 +
    1.59 +namespace Assimp	{
    1.60 +	// =======================================================================
    1.61 +	// Public interface to Assimp 
    1.62 +	class Importer;
    1.63 +	class Exporter; // export.hpp
    1.64 +	class IOStream;
    1.65 +	class IOSystem;
    1.66 +	class ProgressHandler;
    1.67 +
    1.68 +	// =======================================================================
    1.69 +	// Plugin development
    1.70 +	//
    1.71 +	// Include the following headers for the declarations:
    1.72 +	// BaseImporter.h
    1.73 +	// BaseProcess.h
    1.74 +	class BaseImporter;
    1.75 +	class BaseProcess;
    1.76 +	class SharedPostProcessInfo;
    1.77 +	class BatchLoader; 
    1.78 +
    1.79 +	// =======================================================================
    1.80 +	// Holy stuff, only for members of the high council of the Jedi.
    1.81 +	class ImporterPimpl;
    1.82 +	class ExporterPimpl; // export.hpp
    1.83 +} //! namespace Assimp
    1.84 +
    1.85 +#define AI_PROPERTY_WAS_NOT_EXISTING 0xffffffff
    1.86 +
    1.87 +struct aiScene;
    1.88 +
    1.89 +// importerdesc.h
    1.90 +struct aiImporterDesc;
    1.91 +
    1.92 +/** @namespace Assimp Assimp's CPP-API and all internal APIs */
    1.93 +namespace Assimp	{
    1.94 +
    1.95 +// ----------------------------------------------------------------------------------
    1.96 +/** CPP-API: The Importer class forms an C++ interface to the functionality of the 
    1.97 +*   Open Asset Import Library.
    1.98 +*
    1.99 +* Create an object of this class and call ReadFile() to import a file. 
   1.100 +* If the import succeeds, the function returns a pointer to the imported data. 
   1.101 +* The data remains property of the object, it is intended to be accessed 
   1.102 +* read-only. The imported data will be destroyed along with the Importer 
   1.103 +* object. If the import fails, ReadFile() returns a NULL pointer. In this
   1.104 +* case you can retrieve a human-readable error description be calling 
   1.105 +* GetErrorString(). You can call ReadFile() multiple times with a single Importer
   1.106 +* instance. Actually, constructing Importer objects involves quite many
   1.107 +* allocations and may take some time, so it's better to reuse them as often as
   1.108 +* possible.
   1.109 +*
   1.110 +* If you need the Importer to do custom file handling to access the files,
   1.111 +* implement IOSystem and IOStream and supply an instance of your custom 
   1.112 +* IOSystem implementation by calling SetIOHandler() before calling ReadFile().
   1.113 +* If you do not assign a custion IO handler, a default handler using the 
   1.114 +* standard C++ IO logic will be used.
   1.115 +*
   1.116 +* @note One Importer instance is not thread-safe. If you use multiple
   1.117 +* threads for loading, each thread should maintain its own Importer instance.
   1.118 +*/
   1.119 +class ASSIMP_API Importer	{
   1.120 +
   1.121 +public:
   1.122 +
   1.123 +	// -------------------------------------------------------------------
   1.124 +	/** Constructor. Creates an empty importer object. 
   1.125 +	 * 
   1.126 +	 * Call ReadFile() to start the import process. The configuration
   1.127 +	 * property table is initially empty.
   1.128 +	 */
   1.129 +	Importer();
   1.130 +
   1.131 +	// -------------------------------------------------------------------
   1.132 +	/** Copy constructor.
   1.133 +	 * 
   1.134 +	 * This copies the configuration properties of another Importer.
   1.135 +	 * If this Importer owns a scene it won't be copied.
   1.136 +	 * Call ReadFile() to start the import process.
   1.137 +	 */
   1.138 +	Importer(const Importer& other);
   1.139 +
   1.140 +	// -------------------------------------------------------------------
   1.141 +	/** Destructor. The object kept ownership of the imported data,
   1.142 +	 * which now will be destroyed along with the object. 
   1.143 +	 */
   1.144 +	~Importer();
   1.145 +
   1.146 +
   1.147 +	// -------------------------------------------------------------------
   1.148 +	/** Registers a new loader.
   1.149 +	 *
   1.150 +	 * @param pImp Importer to be added. The Importer instance takes 
   1.151 +	 *   ownership of the pointer, so it will be automatically deleted
   1.152 +	 *   with the Importer instance.
   1.153 +	 * @return AI_SUCCESS if the loader has been added. The registration
   1.154 +	 *   fails if there is already a loader for a specific file extension.
   1.155 +	 */
   1.156 +	aiReturn RegisterLoader(BaseImporter* pImp);
   1.157 +
   1.158 +	// -------------------------------------------------------------------
   1.159 +	/** Unregisters a loader.
   1.160 +	 *
   1.161 +	 * @param pImp Importer to be unregistered.
   1.162 +	 * @return AI_SUCCESS if the loader has been removed. The function
   1.163 +	 *   fails if the loader is currently in use (this could happen
   1.164 +	 *   if the #Importer instance is used by more than one thread) or
   1.165 +	 *   if it has not yet been registered.
   1.166 +	 */
   1.167 +	aiReturn UnregisterLoader(BaseImporter* pImp);
   1.168 +
   1.169 +	// -------------------------------------------------------------------
   1.170 +	/** Registers a new post-process step.
   1.171 +	 *
   1.172 +	 * At the moment, there's a small limitation: new post processing 
   1.173 +	 * steps are added to end of the list, or in other words, executed 
   1.174 +	 * last, after all built-in steps.
   1.175 +	 * @param pImp Post-process step to be added. The Importer instance 
   1.176 +	 *   takes ownership of the pointer, so it will be automatically 
   1.177 +	 *   deleted with the Importer instance.
   1.178 +	 * @return AI_SUCCESS if the step has been added correctly.
   1.179 +	 */
   1.180 +	aiReturn RegisterPPStep(BaseProcess* pImp);
   1.181 +
   1.182 +	// -------------------------------------------------------------------
   1.183 +	/** Unregisters a post-process step.
   1.184 +	 *
   1.185 +	 * @param pImp Step to be unregistered. 
   1.186 +	 * @return AI_SUCCESS if the step has been removed. The function
   1.187 +	 *   fails if the step is currently in use (this could happen
   1.188 +	 *   if the #Importer instance is used by more than one thread) or
   1.189 +	 *   if it has not yet been registered.
   1.190 +	 */
   1.191 +	aiReturn UnregisterPPStep(BaseProcess* pImp);
   1.192 +
   1.193 +
   1.194 +	// -------------------------------------------------------------------
   1.195 +	/** Set an integer configuration property.
   1.196 +	 * @param szName Name of the property. All supported properties
   1.197 +	 *   are defined in the aiConfig.g header (all constants share the
   1.198 +	 *   prefix AI_CONFIG_XXX and are simple strings).
   1.199 +	 * @param iValue New value of the property
   1.200 +	 * @param bWasExisting Optional pointer to receive true if the
   1.201 +	 *   property was set before. The new value replaces the previous value
   1.202 +	 *   in this case.
   1.203 +	 * @note Property of different types (float, int, string ..) are kept
   1.204 +	 *   on different stacks, so calling SetPropertyInteger() for a 
   1.205 +	 *   floating-point property has no effect - the loader will call
   1.206 +	 *   GetPropertyFloat() to read the property, but it won't be there.
   1.207 +	 */
   1.208 +	void SetPropertyInteger(const char* szName, int iValue, 
   1.209 +		bool* bWasExisting = NULL);
   1.210 +
   1.211 +	// -------------------------------------------------------------------
   1.212 +	/** Set a boolean configuration property. Boolean properties
   1.213 +	 *  are stored on the integer stack internally so it's possible
   1.214 +	 *  to set them via #SetPropertyBool and query them with
   1.215 +	 *  #GetPropertyBool and vice versa.
   1.216 +	 * @see SetPropertyInteger()
   1.217 +	 */
   1.218 +	void SetPropertyBool(const char* szName, bool value, bool* bWasExisting = NULL)	{
   1.219 +		SetPropertyInteger(szName,value,bWasExisting);
   1.220 +	}
   1.221 +
   1.222 +	// -------------------------------------------------------------------
   1.223 +	/** Set a floating-point configuration property.
   1.224 +	 * @see SetPropertyInteger()
   1.225 +	 */
   1.226 +	void SetPropertyFloat(const char* szName, float fValue, 
   1.227 +		bool* bWasExisting = NULL);
   1.228 +
   1.229 +	// -------------------------------------------------------------------
   1.230 +	/** Set a string configuration property.
   1.231 +	 * @see SetPropertyInteger()
   1.232 +	 */
   1.233 +	void SetPropertyString(const char* szName, const std::string& sValue, 
   1.234 +		bool* bWasExisting = NULL);
   1.235 +
   1.236 +	// -------------------------------------------------------------------
   1.237 +	/** Get a configuration property.
   1.238 +	 * @param szName Name of the property. All supported properties
   1.239 +	 *   are defined in the aiConfig.g header (all constants share the
   1.240 +	 *   prefix AI_CONFIG_XXX).
   1.241 +	 * @param iErrorReturn Value that is returned if the property 
   1.242 +	 *   is not found. 
   1.243 +	 * @return Current value of the property
   1.244 +	 * @note Property of different types (float, int, string ..) are kept
   1.245 +	 *   on different lists, so calling SetPropertyInteger() for a 
   1.246 +	 *   floating-point property has no effect - the loader will call
   1.247 +	 *   GetPropertyFloat() to read the property, but it won't be there.
   1.248 +	 */
   1.249 +	int GetPropertyInteger(const char* szName, 
   1.250 +		int iErrorReturn = 0xffffffff) const;
   1.251 +
   1.252 +	// -------------------------------------------------------------------
   1.253 +	/** Get a boolean configuration property. Boolean properties
   1.254 +	 *  are stored on the integer stack internally so it's possible
   1.255 +	 *  to set them via #SetPropertyBool and query them with
   1.256 +	 *  #GetPropertyBool and vice versa.
   1.257 +	 * @see GetPropertyInteger()
   1.258 +	 */
   1.259 +	bool GetPropertyBool(const char* szName, bool bErrorReturn = false) const {
   1.260 +		return GetPropertyInteger(szName,bErrorReturn)!=0;
   1.261 +	}
   1.262 +
   1.263 +	// -------------------------------------------------------------------
   1.264 +	/** Get a floating-point configuration property
   1.265 +	 * @see GetPropertyInteger()
   1.266 +	 */
   1.267 +	float GetPropertyFloat(const char* szName, 
   1.268 +		float fErrorReturn = 10e10f) const;
   1.269 +
   1.270 +	// -------------------------------------------------------------------
   1.271 +	/** Get a string configuration property
   1.272 +	 *
   1.273 +	 *  The return value remains valid until the property is modified.
   1.274 +	 * @see GetPropertyInteger()
   1.275 +	 */
   1.276 +	const std::string& GetPropertyString(const char* szName,
   1.277 +		const std::string& sErrorReturn = "") const;
   1.278 +
   1.279 +	// -------------------------------------------------------------------
   1.280 +	/** Supplies a custom IO handler to the importer to use to open and
   1.281 +	 * access files. If you need the importer to use custion IO logic to 
   1.282 +	 * access the files, you need to provide a custom implementation of 
   1.283 +	 * IOSystem and IOFile to the importer. Then create an instance of 
   1.284 +	 * your custion IOSystem implementation and supply it by this function.
   1.285 +	 *
   1.286 +	 * The Importer takes ownership of the object and will destroy it 
   1.287 +	 * afterwards. The previously assigned handler will be deleted.
   1.288 +	 * Pass NULL to take again ownership of your IOSystem and reset Assimp
   1.289 +	 * to use its default implementation.
   1.290 +	 *
   1.291 +	 * @param pIOHandler The IO handler to be used in all file accesses 
   1.292 +	 *   of the Importer. 
   1.293 +	 */
   1.294 +	void SetIOHandler( IOSystem* pIOHandler);
   1.295 +
   1.296 +	// -------------------------------------------------------------------
   1.297 +	/** Retrieves the IO handler that is currently set.
   1.298 +	 * You can use #IsDefaultIOHandler() to check whether the returned
   1.299 +	 * interface is the default IO handler provided by ASSIMP. The default
   1.300 +	 * handler is active as long the application doesn't supply its own
   1.301 +	 * custom IO handler via #SetIOHandler().
   1.302 +	 * @return A valid IOSystem interface, never NULL.
   1.303 +	 */
   1.304 +	IOSystem* GetIOHandler() const;
   1.305 +
   1.306 +	// -------------------------------------------------------------------
   1.307 +	/** Checks whether a default IO handler is active 
   1.308 +	 * A default handler is active as long the application doesn't 
   1.309 +	 * supply its own custom IO handler via #SetIOHandler().
   1.310 +	 * @return true by default
   1.311 +	 */
   1.312 +	bool IsDefaultIOHandler() const;
   1.313 +
   1.314 +	// -------------------------------------------------------------------
   1.315 +	/** Supplies a custom progress handler to the importer. This 
   1.316 +	 *  interface exposes a #Update() callback, which is called
   1.317 +	 *  more or less periodically (please don't sue us if it
   1.318 +	 *  isn't as periodically as you'd like it to have ...).
   1.319 +	 *  This can be used to implement progress bars and loading
   1.320 +	 *  timeouts. 
   1.321 +	 *  @param pHandler Progress callback interface. Pass NULL to 
   1.322 +	 *    disable progress reporting. 
   1.323 +	 *  @note Progress handlers can be used to abort the loading
   1.324 +	 *    at almost any time.*/
   1.325 +	void SetProgressHandler ( ProgressHandler* pHandler );
   1.326 +
   1.327 +	// -------------------------------------------------------------------
   1.328 +	/** Retrieves the progress handler that is currently set. 
   1.329 +	 * You can use #IsDefaultProgressHandler() to check whether the returned
   1.330 +	 * interface is the default handler provided by ASSIMP. The default
   1.331 +	 * handler is active as long the application doesn't supply its own
   1.332 +	 * custom handler via #SetProgressHandler().
   1.333 +	 * @return A valid ProgressHandler interface, never NULL.
   1.334 +	 */
   1.335 +	ProgressHandler* GetProgressHandler() const;
   1.336 +
   1.337 +	// -------------------------------------------------------------------
   1.338 +	/** Checks whether a default progress handler is active 
   1.339 +	 * A default handler is active as long the application doesn't 
   1.340 +	 * supply its own custom progress handler via #SetProgressHandler().
   1.341 +	 * @return true by default
   1.342 +	 */
   1.343 +	bool IsDefaultProgressHandler() const;
   1.344 +
   1.345 +	// -------------------------------------------------------------------
   1.346 +	/** @brief Check whether a given set of postprocessing flags
   1.347 +	 *  is supported.
   1.348 +	 *
   1.349 +	 *  Some flags are mutually exclusive, others are probably
   1.350 +	 *  not available because your excluded them from your
   1.351 +	 *  Assimp builds. Calling this function is recommended if 
   1.352 +	 *  you're unsure.
   1.353 +	 *
   1.354 +	 *  @param pFlags Bitwise combination of the aiPostProcess flags.
   1.355 +	 *  @return true if this flag combination is fine.
   1.356 +	 */
   1.357 +	bool ValidateFlags(unsigned int pFlags) const;
   1.358 +
   1.359 +	// -------------------------------------------------------------------
   1.360 +	/** Reads the given file and returns its contents if successful. 
   1.361 +	 * 
   1.362 +	 * If the call succeeds, the contents of the file are returned as a 
   1.363 +	 * pointer to an aiScene object. The returned data is intended to be 
   1.364 +	 * read-only, the importer object keeps ownership of the data and will
   1.365 +	 * destroy it upon destruction. If the import fails, NULL is returned.
   1.366 +	 * A human-readable error description can be retrieved by calling 
   1.367 +	 * GetErrorString(). The previous scene will be deleted during this call.
   1.368 +	 * @param pFile Path and filename to the file to be imported.
   1.369 +	 * @param pFlags Optional post processing steps to be executed after 
   1.370 +	 *   a successful import. Provide a bitwise combination of the 
   1.371 +	 *   #aiPostProcessSteps flags. If you wish to inspect the imported
   1.372 +	 *   scene first in order to fine-tune your post-processing setup,
   1.373 +	 *   consider to use #ApplyPostProcessing().
   1.374 +	 * @return A pointer to the imported data, NULL if the import failed.
   1.375 +	 *   The pointer to the scene remains in possession of the Importer
   1.376 +	 *   instance. Use GetOrphanedScene() to take ownership of it.
   1.377 +	 *
   1.378 +	 * @note Assimp is able to determine the file format of a file
   1.379 +	 * automatically. 
   1.380 +	 */
   1.381 +	const aiScene* ReadFile(
   1.382 +		const char* pFile, 
   1.383 +		unsigned int pFlags);
   1.384 +
   1.385 +	// -------------------------------------------------------------------
   1.386 +	/** Reads the given file from a memory buffer and returns its
   1.387 +	 *  contents if successful.
   1.388 +	 * 
   1.389 +	 * If the call succeeds, the contents of the file are returned as a 
   1.390 +	 * pointer to an aiScene object. The returned data is intended to be 
   1.391 +	 * read-only, the importer object keeps ownership of the data and will
   1.392 +	 * destroy it upon destruction. If the import fails, NULL is returned.
   1.393 +	 * A human-readable error description can be retrieved by calling 
   1.394 +	 * GetErrorString(). The previous scene will be deleted during this call.
   1.395 +	 * Calling this method doesn't affect the active IOSystem.
   1.396 +	 * @param pBuffer Pointer to the file data
   1.397 +	 * @param pLength Length of pBuffer, in bytes
   1.398 +	 * @param pFlags Optional post processing steps to be executed after 
   1.399 +	 *   a successful import. Provide a bitwise combination of the 
   1.400 +	 *   #aiPostProcessSteps flags. If you wish to inspect the imported
   1.401 +	 *   scene first in order to fine-tune your post-processing setup,
   1.402 +	 *   consider to use #ApplyPostProcessing().
   1.403 +	 * @param pHint An additional hint to the library. If this is a non
   1.404 +	 *   empty string, the library looks for a loader to support 
   1.405 +	 *   the file extension specified by pHint and passes the file to
   1.406 +	 *   the first matching loader. If this loader is unable to completely
   1.407 +	 *   the request, the library continues and tries to determine the
   1.408 +	 *   file format on its own, a task that may or may not be successful.
   1.409 +	 *   Check the return value, and you'll know ...
   1.410 +	 * @return A pointer to the imported data, NULL if the import failed.
   1.411 +	 *   The pointer to the scene remains in possession of the Importer
   1.412 +	 *   instance. Use GetOrphanedScene() to take ownership of it.
   1.413 +	 *
   1.414 +	 * @note This is a straightforward way to decode models from memory
   1.415 +	 * buffers, but it doesn't handle model formats that spread their 
   1.416 +	 * data across multiple files or even directories. Examples include
   1.417 +	 * OBJ or MD3, which outsource parts of their material info into
   1.418 +	 * external scripts. If you need full functionality, provide
   1.419 +	 * a custom IOSystem to make Assimp find these files and use
   1.420 +	 * the regular ReadFile() API.
   1.421 +	 */
   1.422 +	const aiScene* ReadFileFromMemory( 
   1.423 +		const void* pBuffer,
   1.424 +		size_t pLength,
   1.425 +		unsigned int pFlags,
   1.426 +		const char* pHint = "");
   1.427 +
   1.428 +	// -------------------------------------------------------------------
   1.429 +	/** Apply post-processing to an already-imported scene.
   1.430 +	 *
   1.431 +	 *  This is strictly equivalent to calling #ReadFile() with the same
   1.432 +	 *  flags. However, you can use this separate function to inspect
   1.433 +	 *  the imported scene first to fine-tune your post-processing setup.
   1.434 +	 *  @param pFlags Provide a bitwise combination of the 
   1.435 +	 *   #aiPostProcessSteps flags.
   1.436 +	 *  @return A pointer to the post-processed data. This is still the
   1.437 +	 *   same as the pointer returned by #ReadFile(). However, if
   1.438 +	 *   post-processing fails, the scene could now be NULL.
   1.439 +	 *   That's quite a rare case, post processing steps are not really
   1.440 +	 *   designed to 'fail'. To be exact, the #aiProcess_ValidateDS
   1.441 +	 *   flag is currently the only post processing step which can actually
   1.442 +	 *   cause the scene to be reset to NULL.
   1.443 +	 *
   1.444 +	 *  @note The method does nothing if no scene is currently bound
   1.445 +	 *    to the #Importer instance.  */
   1.446 +	const aiScene* ApplyPostProcessing(unsigned int pFlags);
   1.447 +
   1.448 +	// -------------------------------------------------------------------
   1.449 +	/** @brief Reads the given file and returns its contents if successful. 
   1.450 +	 *
   1.451 +	 * This function is provided for backward compatibility.
   1.452 +	 * See the const char* version for detailled docs.
   1.453 +	 * @see ReadFile(const char*, pFlags)  */
   1.454 +	const aiScene* ReadFile(
   1.455 +		const std::string& pFile, 
   1.456 +		unsigned int pFlags);
   1.457 +
   1.458 +	// -------------------------------------------------------------------
   1.459 +	/** Frees the current scene.
   1.460 +	 *
   1.461 +	 *  The function does nothing if no scene has previously been 
   1.462 +	 *  read via ReadFile(). FreeScene() is called automatically by the
   1.463 +	 *  destructor and ReadFile() itself.  */
   1.464 +	void FreeScene( );
   1.465 +
   1.466 +	// -------------------------------------------------------------------
   1.467 +	/** Returns an error description of an error that occurred in ReadFile(). 
   1.468 +	 *
   1.469 +	 * Returns an empty string if no error occurred.
   1.470 +	 * @return A description of the last error, an empty string if no 
   1.471 +	 *   error occurred. The string is never NULL.
   1.472 +	 *
   1.473 +	 * @note The returned function remains valid until one of the 
   1.474 +	 * following methods is called: #ReadFile(), #FreeScene(). */
   1.475 +	const char* GetErrorString() const;
   1.476 +
   1.477 +	// -------------------------------------------------------------------
   1.478 +	/** Returns the scene loaded by the last successful call to ReadFile()
   1.479 +	 *
   1.480 +	 * @return Current scene or NULL if there is currently no scene loaded */
   1.481 +	const aiScene* GetScene() const;
   1.482 +
   1.483 +	// -------------------------------------------------------------------
   1.484 +	/** Returns the scene loaded by the last successful call to ReadFile()
   1.485 +	 *  and releases the scene from the ownership of the Importer 
   1.486 +	 *  instance. The application is now responsible for deleting the
   1.487 +	 *  scene. Any further calls to GetScene() or GetOrphanedScene()
   1.488 +	 *  will return NULL - until a new scene has been loaded via ReadFile().
   1.489 +	 *
   1.490 +	 * @return Current scene or NULL if there is currently no scene loaded
   1.491 +	 * @note Use this method with maximal caution, and only if you have to.
   1.492 +	 *   By design, aiScene's are exclusively maintained, allocated and
   1.493 +	 *   deallocated by Assimp and no one else. The reasoning behind this
   1.494 +	 *   is the golden rule that deallocations should always be done
   1.495 +	 *   by the module that did the original allocation because heaps
   1.496 +	 *   are not necessarily shared. GetOrphanedScene() enforces you
   1.497 +	 *   to delete the returned scene by yourself, but this will only
   1.498 +	 *   be fine if and only if you're using the same heap as assimp.
   1.499 +	 *   On Windows, it's typically fine provided everything is linked
   1.500 +	 *   against the multithreaded-dll version of the runtime library.
   1.501 +	 *   It will work as well for static linkage with Assimp.*/
   1.502 +	aiScene* GetOrphanedScene();
   1.503 +
   1.504 +
   1.505 +
   1.506 +
   1.507 +	// -------------------------------------------------------------------
   1.508 +	/** Returns whether a given file extension is supported by ASSIMP.
   1.509 +	 *
   1.510 +	 * @param szExtension Extension to be checked.
   1.511 +	 *   Must include a trailing dot '.'. Example: ".3ds", ".md3".
   1.512 +	 *   Cases-insensitive.
   1.513 +	 * @return true if the extension is supported, false otherwise */
   1.514 +	bool IsExtensionSupported(const char* szExtension) const;
   1.515 +
   1.516 +	// -------------------------------------------------------------------
   1.517 +	/** @brief Returns whether a given file extension is supported by ASSIMP.
   1.518 +	 *
   1.519 +	 * This function is provided for backward compatibility.
   1.520 +	 * See the const char* version for detailed and up-to-date docs.
   1.521 +	 * @see IsExtensionSupported(const char*) */
   1.522 +	inline bool IsExtensionSupported(const std::string& szExtension) const;
   1.523 +
   1.524 +	// -------------------------------------------------------------------
   1.525 +	/** Get a full list of all file extensions supported by ASSIMP.
   1.526 +	 *
   1.527 +	 * If a file extension is contained in the list this does of course not
   1.528 +	 * mean that ASSIMP is able to load all files with this extension ---
   1.529 +     * it simply means there is an importer loaded which claims to handle
   1.530 +	 * files with this file extension.
   1.531 +	 * @param szOut String to receive the extension list. 
   1.532 +	 *   Format of the list: "*.3ds;*.obj;*.dae". This is useful for
   1.533 +	 *   use with the WinAPI call GetOpenFileName(Ex). */
   1.534 +	void GetExtensionList(aiString& szOut) const;
   1.535 +
   1.536 +	// -------------------------------------------------------------------
   1.537 +	/** @brief Get a full list of all file extensions supported by ASSIMP.
   1.538 +	 *
   1.539 +	 * This function is provided for backward compatibility.
   1.540 +	 * See the aiString version for detailed and up-to-date docs.
   1.541 +	 * @see GetExtensionList(aiString&)*/
   1.542 +	inline void GetExtensionList(std::string& szOut) const;
   1.543 +
   1.544 +	// -------------------------------------------------------------------
   1.545 +	/** Get the number of importrs currently registered with Assimp. */
   1.546 +	size_t GetImporterCount() const;
   1.547 +
   1.548 +	// -------------------------------------------------------------------
   1.549 +	/** Get meta data for the importer corresponding to a specific index..
   1.550 +	*
   1.551 +	*  For the declaration of #aiImporterDesc, include <assimp/importerdesc.h>.
   1.552 +	*  @param index Index to query, must be within [0,GetImporterCount())
   1.553 +	*  @return Importer meta data structure, NULL if the index does not
   1.554 +	*     exist or if the importer doesn't offer meta information (
   1.555 +	*     importers may do this at the cost of being hated by their peers).*/
   1.556 +	const aiImporterDesc* GetImporterInfo(size_t index) const;
   1.557 +
   1.558 +	// -------------------------------------------------------------------
   1.559 +	/** Find the importer corresponding to a specific index.
   1.560 +	*
   1.561 +	*  @param index Index to query, must be within [0,GetImporterCount())
   1.562 +	*  @return Importer instance. NULL if the index does not
   1.563 +	*     exist. */
   1.564 +	BaseImporter* GetImporter(size_t index) const;
   1.565 +
   1.566 +	// -------------------------------------------------------------------
   1.567 +	/** Find the importer corresponding to a specific file extension.
   1.568 +	*
   1.569 +	*  This is quite similar to #IsExtensionSupported except a
   1.570 +	*  BaseImporter instance is returned.
   1.571 +	*  @param szExtension Extension to check for. The following formats
   1.572 +	*    are recognized (BAH being the file extension): "BAH" (comparison
   1.573 +	*    is case-insensitive), ".bah", "*.bah" (wild card and dot
   1.574 +	*    characters at the beginning of the extension are skipped).
   1.575 +	*  @return NULL if no importer is found*/
   1.576 +	BaseImporter* GetImporter (const char* szExtension) const;
   1.577 +
   1.578 +	// -------------------------------------------------------------------
   1.579 +	/** Find the importer index corresponding to a specific file extension.
   1.580 +	*
   1.581 +	*  @param szExtension Extension to check for. The following formats
   1.582 +	*    are recognized (BAH being the file extension): "BAH" (comparison
   1.583 +	*    is case-insensitive), ".bah", "*.bah" (wild card and dot
   1.584 +	*    characters at the beginning of the extension are skipped).
   1.585 +	*  @return (size_t)-1 if no importer is found */
   1.586 +	size_t GetImporterIndex (const char* szExtension) const;
   1.587 +
   1.588 +
   1.589 +
   1.590 +
   1.591 +	// -------------------------------------------------------------------
   1.592 +	/** Returns the storage allocated by ASSIMP to hold the scene data
   1.593 +	 * in memory.
   1.594 +	 *
   1.595 +	 * This refers to the currently loaded file, see #ReadFile().
   1.596 +	 * @param in Data structure to be filled. 
   1.597 +	 * @note The returned memory statistics refer to the actual
   1.598 +	 *   size of the use data of the aiScene. Heap-related overhead
   1.599 +	 *   is (naturally) not included.*/
   1.600 +	void GetMemoryRequirements(aiMemoryInfo& in) const;
   1.601 +
   1.602 +	// -------------------------------------------------------------------
   1.603 +	/** Enables "extra verbose" mode. 
   1.604 +	 *
   1.605 +	 * 'Extra verbose' means the data structure is validated after *every*
   1.606 +	 * single post processing step to make sure everyone modifies the data
   1.607 +	 * structure in a well-defined manner. This is a debug feature and not
   1.608 +	 * intended for use in production environments. */
   1.609 +	void SetExtraVerbose(bool bDo);
   1.610 +
   1.611 +
   1.612 +	// -------------------------------------------------------------------
   1.613 +	/** Private, do not use. */
   1.614 +	ImporterPimpl* Pimpl() { return pimpl; };
   1.615 +	const ImporterPimpl* Pimpl() const { return pimpl; };
   1.616 +
   1.617 +protected:
   1.618 +
   1.619 +	// Just because we don't want you to know how we're hacking around.
   1.620 +	ImporterPimpl* pimpl;
   1.621 +}; //! class Importer
   1.622 +
   1.623 +
   1.624 +// ----------------------------------------------------------------------------
   1.625 +// For compatibility, the interface of some functions taking a std::string was
   1.626 +// changed to const char* to avoid crashes between binary incompatible STL 
   1.627 +// versions. This code her is inlined,  so it shouldn't cause any problems.
   1.628 +// ----------------------------------------------------------------------------
   1.629 +
   1.630 +// ----------------------------------------------------------------------------
   1.631 +AI_FORCE_INLINE const aiScene* Importer::ReadFile( const std::string& pFile,unsigned int pFlags){
   1.632 +	return ReadFile(pFile.c_str(),pFlags);
   1.633 +}
   1.634 +// ----------------------------------------------------------------------------
   1.635 +AI_FORCE_INLINE void Importer::GetExtensionList(std::string& szOut) const	{
   1.636 +	aiString s;
   1.637 +	GetExtensionList(s);
   1.638 +	szOut = s.data;
   1.639 +}
   1.640 +// ----------------------------------------------------------------------------
   1.641 +AI_FORCE_INLINE bool Importer::IsExtensionSupported(const std::string& szExtension) const	{
   1.642 +	return IsExtensionSupported(szExtension.c_str());
   1.643 +}
   1.644 +
   1.645 +} // !namespace Assimp
   1.646 +#endif // INCLUDED_AI_ASSIMP_HPP