vrshoot

annotate libs/assimp/assimp/Importer.hpp @ 0:b2f14e535253

find changesets by author, revision, files, or words in the commit message
initial commit
author John Tsiombikas <nuclear@member.fsf.org>
date Sat, 01 Feb 2014 19:58:19 +0200
parents
children
rev   line source
nuclear@0 1 /*
nuclear@0 2 ---------------------------------------------------------------------------
nuclear@0 3 Open Asset Import Library (assimp)
nuclear@0 4 ---------------------------------------------------------------------------
nuclear@0 5
nuclear@0 6 Copyright (c) 2006-2012, assimp team
nuclear@0 7
nuclear@0 8 All rights reserved.
nuclear@0 9
nuclear@0 10 Redistribution and use of this software in source and binary forms,
nuclear@0 11 with or without modification, are permitted provided that the following
nuclear@0 12 conditions are met:
nuclear@0 13
nuclear@0 14 * Redistributions of source code must retain the above
nuclear@0 15 copyright notice, this list of conditions and the
nuclear@0 16 following disclaimer.
nuclear@0 17
nuclear@0 18 * Redistributions in binary form must reproduce the above
nuclear@0 19 copyright notice, this list of conditions and the
nuclear@0 20 following disclaimer in the documentation and/or other
nuclear@0 21 materials provided with the distribution.
nuclear@0 22
nuclear@0 23 * Neither the name of the assimp team, nor the names of its
nuclear@0 24 contributors may be used to endorse or promote products
nuclear@0 25 derived from this software without specific prior
nuclear@0 26 written permission of the assimp team.
nuclear@0 27
nuclear@0 28 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
nuclear@0 29 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
nuclear@0 30 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
nuclear@0 31 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
nuclear@0 32 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
nuclear@0 33 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
nuclear@0 34 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
nuclear@0 35 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
nuclear@0 36 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
nuclear@0 37 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
nuclear@0 38 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
nuclear@0 39 ---------------------------------------------------------------------------
nuclear@0 40 */
nuclear@0 41
nuclear@0 42 /** @file assimp.hpp
nuclear@0 43 * @brief Defines the C++-API to the Open Asset Import Library.
nuclear@0 44 */
nuclear@0 45 #ifndef INCLUDED_AI_ASSIMP_HPP
nuclear@0 46 #define INCLUDED_AI_ASSIMP_HPP
nuclear@0 47
nuclear@0 48 #ifndef __cplusplus
nuclear@0 49 # error This header requires C++ to be used. Use assimp.h for plain C.
nuclear@0 50 #endif
nuclear@0 51
nuclear@0 52 // Public ASSIMP data structures
nuclear@0 53 #include "types.h"
nuclear@0 54 #include "config.h"
nuclear@0 55
nuclear@0 56 namespace Assimp {
nuclear@0 57 // =======================================================================
nuclear@0 58 // Public interface to Assimp
nuclear@0 59 class Importer;
nuclear@0 60 class Exporter; // export.hpp
nuclear@0 61 class IOStream;
nuclear@0 62 class IOSystem;
nuclear@0 63 class ProgressHandler;
nuclear@0 64
nuclear@0 65 // =======================================================================
nuclear@0 66 // Plugin development
nuclear@0 67 //
nuclear@0 68 // Include the following headers for the declarations:
nuclear@0 69 // BaseImporter.h
nuclear@0 70 // BaseProcess.h
nuclear@0 71 class BaseImporter;
nuclear@0 72 class BaseProcess;
nuclear@0 73 class SharedPostProcessInfo;
nuclear@0 74 class BatchLoader;
nuclear@0 75
nuclear@0 76 // =======================================================================
nuclear@0 77 // Holy stuff, only for members of the high council of the Jedi.
nuclear@0 78 class ImporterPimpl;
nuclear@0 79 class ExporterPimpl; // export.hpp
nuclear@0 80 } //! namespace Assimp
nuclear@0 81
nuclear@0 82 #define AI_PROPERTY_WAS_NOT_EXISTING 0xffffffff
nuclear@0 83
nuclear@0 84 struct aiScene;
nuclear@0 85
nuclear@0 86 // importerdesc.h
nuclear@0 87 struct aiImporterDesc;
nuclear@0 88
nuclear@0 89 /** @namespace Assimp Assimp's CPP-API and all internal APIs */
nuclear@0 90 namespace Assimp {
nuclear@0 91
nuclear@0 92 // ----------------------------------------------------------------------------------
nuclear@0 93 /** CPP-API: The Importer class forms an C++ interface to the functionality of the
nuclear@0 94 * Open Asset Import Library.
nuclear@0 95 *
nuclear@0 96 * Create an object of this class and call ReadFile() to import a file.
nuclear@0 97 * If the import succeeds, the function returns a pointer to the imported data.
nuclear@0 98 * The data remains property of the object, it is intended to be accessed
nuclear@0 99 * read-only. The imported data will be destroyed along with the Importer
nuclear@0 100 * object. If the import fails, ReadFile() returns a NULL pointer. In this
nuclear@0 101 * case you can retrieve a human-readable error description be calling
nuclear@0 102 * GetErrorString(). You can call ReadFile() multiple times with a single Importer
nuclear@0 103 * instance. Actually, constructing Importer objects involves quite many
nuclear@0 104 * allocations and may take some time, so it's better to reuse them as often as
nuclear@0 105 * possible.
nuclear@0 106 *
nuclear@0 107 * If you need the Importer to do custom file handling to access the files,
nuclear@0 108 * implement IOSystem and IOStream and supply an instance of your custom
nuclear@0 109 * IOSystem implementation by calling SetIOHandler() before calling ReadFile().
nuclear@0 110 * If you do not assign a custion IO handler, a default handler using the
nuclear@0 111 * standard C++ IO logic will be used.
nuclear@0 112 *
nuclear@0 113 * @note One Importer instance is not thread-safe. If you use multiple
nuclear@0 114 * threads for loading, each thread should maintain its own Importer instance.
nuclear@0 115 */
nuclear@0 116 class ASSIMP_API Importer {
nuclear@0 117
nuclear@0 118 public:
nuclear@0 119
nuclear@0 120 // -------------------------------------------------------------------
nuclear@0 121 /** Constructor. Creates an empty importer object.
nuclear@0 122 *
nuclear@0 123 * Call ReadFile() to start the import process. The configuration
nuclear@0 124 * property table is initially empty.
nuclear@0 125 */
nuclear@0 126 Importer();
nuclear@0 127
nuclear@0 128 // -------------------------------------------------------------------
nuclear@0 129 /** Copy constructor.
nuclear@0 130 *
nuclear@0 131 * This copies the configuration properties of another Importer.
nuclear@0 132 * If this Importer owns a scene it won't be copied.
nuclear@0 133 * Call ReadFile() to start the import process.
nuclear@0 134 */
nuclear@0 135 Importer(const Importer& other);
nuclear@0 136
nuclear@0 137 // -------------------------------------------------------------------
nuclear@0 138 /** Destructor. The object kept ownership of the imported data,
nuclear@0 139 * which now will be destroyed along with the object.
nuclear@0 140 */
nuclear@0 141 ~Importer();
nuclear@0 142
nuclear@0 143
nuclear@0 144 // -------------------------------------------------------------------
nuclear@0 145 /** Registers a new loader.
nuclear@0 146 *
nuclear@0 147 * @param pImp Importer to be added. The Importer instance takes
nuclear@0 148 * ownership of the pointer, so it will be automatically deleted
nuclear@0 149 * with the Importer instance.
nuclear@0 150 * @return AI_SUCCESS if the loader has been added. The registration
nuclear@0 151 * fails if there is already a loader for a specific file extension.
nuclear@0 152 */
nuclear@0 153 aiReturn RegisterLoader(BaseImporter* pImp);
nuclear@0 154
nuclear@0 155 // -------------------------------------------------------------------
nuclear@0 156 /** Unregisters a loader.
nuclear@0 157 *
nuclear@0 158 * @param pImp Importer to be unregistered.
nuclear@0 159 * @return AI_SUCCESS if the loader has been removed. The function
nuclear@0 160 * fails if the loader is currently in use (this could happen
nuclear@0 161 * if the #Importer instance is used by more than one thread) or
nuclear@0 162 * if it has not yet been registered.
nuclear@0 163 */
nuclear@0 164 aiReturn UnregisterLoader(BaseImporter* pImp);
nuclear@0 165
nuclear@0 166 // -------------------------------------------------------------------
nuclear@0 167 /** Registers a new post-process step.
nuclear@0 168 *
nuclear@0 169 * At the moment, there's a small limitation: new post processing
nuclear@0 170 * steps are added to end of the list, or in other words, executed
nuclear@0 171 * last, after all built-in steps.
nuclear@0 172 * @param pImp Post-process step to be added. The Importer instance
nuclear@0 173 * takes ownership of the pointer, so it will be automatically
nuclear@0 174 * deleted with the Importer instance.
nuclear@0 175 * @return AI_SUCCESS if the step has been added correctly.
nuclear@0 176 */
nuclear@0 177 aiReturn RegisterPPStep(BaseProcess* pImp);
nuclear@0 178
nuclear@0 179 // -------------------------------------------------------------------
nuclear@0 180 /** Unregisters a post-process step.
nuclear@0 181 *
nuclear@0 182 * @param pImp Step to be unregistered.
nuclear@0 183 * @return AI_SUCCESS if the step has been removed. The function
nuclear@0 184 * fails if the step is currently in use (this could happen
nuclear@0 185 * if the #Importer instance is used by more than one thread) or
nuclear@0 186 * if it has not yet been registered.
nuclear@0 187 */
nuclear@0 188 aiReturn UnregisterPPStep(BaseProcess* pImp);
nuclear@0 189
nuclear@0 190
nuclear@0 191 // -------------------------------------------------------------------
nuclear@0 192 /** Set an integer configuration property.
nuclear@0 193 * @param szName Name of the property. All supported properties
nuclear@0 194 * are defined in the aiConfig.g header (all constants share the
nuclear@0 195 * prefix AI_CONFIG_XXX and are simple strings).
nuclear@0 196 * @param iValue New value of the property
nuclear@0 197 * @param bWasExisting Optional pointer to receive true if the
nuclear@0 198 * property was set before. The new value replaces the previous value
nuclear@0 199 * in this case.
nuclear@0 200 * @note Property of different types (float, int, string ..) are kept
nuclear@0 201 * on different stacks, so calling SetPropertyInteger() for a
nuclear@0 202 * floating-point property has no effect - the loader will call
nuclear@0 203 * GetPropertyFloat() to read the property, but it won't be there.
nuclear@0 204 */
nuclear@0 205 void SetPropertyInteger(const char* szName, int iValue,
nuclear@0 206 bool* bWasExisting = NULL);
nuclear@0 207
nuclear@0 208 // -------------------------------------------------------------------
nuclear@0 209 /** Set a boolean configuration property. Boolean properties
nuclear@0 210 * are stored on the integer stack internally so it's possible
nuclear@0 211 * to set them via #SetPropertyBool and query them with
nuclear@0 212 * #GetPropertyBool and vice versa.
nuclear@0 213 * @see SetPropertyInteger()
nuclear@0 214 */
nuclear@0 215 void SetPropertyBool(const char* szName, bool value, bool* bWasExisting = NULL) {
nuclear@0 216 SetPropertyInteger(szName,value,bWasExisting);
nuclear@0 217 }
nuclear@0 218
nuclear@0 219 // -------------------------------------------------------------------
nuclear@0 220 /** Set a floating-point configuration property.
nuclear@0 221 * @see SetPropertyInteger()
nuclear@0 222 */
nuclear@0 223 void SetPropertyFloat(const char* szName, float fValue,
nuclear@0 224 bool* bWasExisting = NULL);
nuclear@0 225
nuclear@0 226 // -------------------------------------------------------------------
nuclear@0 227 /** Set a string configuration property.
nuclear@0 228 * @see SetPropertyInteger()
nuclear@0 229 */
nuclear@0 230 void SetPropertyString(const char* szName, const std::string& sValue,
nuclear@0 231 bool* bWasExisting = NULL);
nuclear@0 232
nuclear@0 233 // -------------------------------------------------------------------
nuclear@0 234 /** Get a configuration property.
nuclear@0 235 * @param szName Name of the property. All supported properties
nuclear@0 236 * are defined in the aiConfig.g header (all constants share the
nuclear@0 237 * prefix AI_CONFIG_XXX).
nuclear@0 238 * @param iErrorReturn Value that is returned if the property
nuclear@0 239 * is not found.
nuclear@0 240 * @return Current value of the property
nuclear@0 241 * @note Property of different types (float, int, string ..) are kept
nuclear@0 242 * on different lists, so calling SetPropertyInteger() for a
nuclear@0 243 * floating-point property has no effect - the loader will call
nuclear@0 244 * GetPropertyFloat() to read the property, but it won't be there.
nuclear@0 245 */
nuclear@0 246 int GetPropertyInteger(const char* szName,
nuclear@0 247 int iErrorReturn = 0xffffffff) const;
nuclear@0 248
nuclear@0 249 // -------------------------------------------------------------------
nuclear@0 250 /** Get a boolean configuration property. Boolean properties
nuclear@0 251 * are stored on the integer stack internally so it's possible
nuclear@0 252 * to set them via #SetPropertyBool and query them with
nuclear@0 253 * #GetPropertyBool and vice versa.
nuclear@0 254 * @see GetPropertyInteger()
nuclear@0 255 */
nuclear@0 256 bool GetPropertyBool(const char* szName, bool bErrorReturn = false) const {
nuclear@0 257 return GetPropertyInteger(szName,bErrorReturn)!=0;
nuclear@0 258 }
nuclear@0 259
nuclear@0 260 // -------------------------------------------------------------------
nuclear@0 261 /** Get a floating-point configuration property
nuclear@0 262 * @see GetPropertyInteger()
nuclear@0 263 */
nuclear@0 264 float GetPropertyFloat(const char* szName,
nuclear@0 265 float fErrorReturn = 10e10f) const;
nuclear@0 266
nuclear@0 267 // -------------------------------------------------------------------
nuclear@0 268 /** Get a string configuration property
nuclear@0 269 *
nuclear@0 270 * The return value remains valid until the property is modified.
nuclear@0 271 * @see GetPropertyInteger()
nuclear@0 272 */
nuclear@0 273 const std::string& GetPropertyString(const char* szName,
nuclear@0 274 const std::string& sErrorReturn = "") const;
nuclear@0 275
nuclear@0 276 // -------------------------------------------------------------------
nuclear@0 277 /** Supplies a custom IO handler to the importer to use to open and
nuclear@0 278 * access files. If you need the importer to use custion IO logic to
nuclear@0 279 * access the files, you need to provide a custom implementation of
nuclear@0 280 * IOSystem and IOFile to the importer. Then create an instance of
nuclear@0 281 * your custion IOSystem implementation and supply it by this function.
nuclear@0 282 *
nuclear@0 283 * The Importer takes ownership of the object and will destroy it
nuclear@0 284 * afterwards. The previously assigned handler will be deleted.
nuclear@0 285 * Pass NULL to take again ownership of your IOSystem and reset Assimp
nuclear@0 286 * to use its default implementation.
nuclear@0 287 *
nuclear@0 288 * @param pIOHandler The IO handler to be used in all file accesses
nuclear@0 289 * of the Importer.
nuclear@0 290 */
nuclear@0 291 void SetIOHandler( IOSystem* pIOHandler);
nuclear@0 292
nuclear@0 293 // -------------------------------------------------------------------
nuclear@0 294 /** Retrieves the IO handler that is currently set.
nuclear@0 295 * You can use #IsDefaultIOHandler() to check whether the returned
nuclear@0 296 * interface is the default IO handler provided by ASSIMP. The default
nuclear@0 297 * handler is active as long the application doesn't supply its own
nuclear@0 298 * custom IO handler via #SetIOHandler().
nuclear@0 299 * @return A valid IOSystem interface, never NULL.
nuclear@0 300 */
nuclear@0 301 IOSystem* GetIOHandler() const;
nuclear@0 302
nuclear@0 303 // -------------------------------------------------------------------
nuclear@0 304 /** Checks whether a default IO handler is active
nuclear@0 305 * A default handler is active as long the application doesn't
nuclear@0 306 * supply its own custom IO handler via #SetIOHandler().
nuclear@0 307 * @return true by default
nuclear@0 308 */
nuclear@0 309 bool IsDefaultIOHandler() const;
nuclear@0 310
nuclear@0 311 // -------------------------------------------------------------------
nuclear@0 312 /** Supplies a custom progress handler to the importer. This
nuclear@0 313 * interface exposes a #Update() callback, which is called
nuclear@0 314 * more or less periodically (please don't sue us if it
nuclear@0 315 * isn't as periodically as you'd like it to have ...).
nuclear@0 316 * This can be used to implement progress bars and loading
nuclear@0 317 * timeouts.
nuclear@0 318 * @param pHandler Progress callback interface. Pass NULL to
nuclear@0 319 * disable progress reporting.
nuclear@0 320 * @note Progress handlers can be used to abort the loading
nuclear@0 321 * at almost any time.*/
nuclear@0 322 void SetProgressHandler ( ProgressHandler* pHandler );
nuclear@0 323
nuclear@0 324 // -------------------------------------------------------------------
nuclear@0 325 /** Retrieves the progress handler that is currently set.
nuclear@0 326 * You can use #IsDefaultProgressHandler() to check whether the returned
nuclear@0 327 * interface is the default handler provided by ASSIMP. The default
nuclear@0 328 * handler is active as long the application doesn't supply its own
nuclear@0 329 * custom handler via #SetProgressHandler().
nuclear@0 330 * @return A valid ProgressHandler interface, never NULL.
nuclear@0 331 */
nuclear@0 332 ProgressHandler* GetProgressHandler() const;
nuclear@0 333
nuclear@0 334 // -------------------------------------------------------------------
nuclear@0 335 /** Checks whether a default progress handler is active
nuclear@0 336 * A default handler is active as long the application doesn't
nuclear@0 337 * supply its own custom progress handler via #SetProgressHandler().
nuclear@0 338 * @return true by default
nuclear@0 339 */
nuclear@0 340 bool IsDefaultProgressHandler() const;
nuclear@0 341
nuclear@0 342 // -------------------------------------------------------------------
nuclear@0 343 /** @brief Check whether a given set of postprocessing flags
nuclear@0 344 * is supported.
nuclear@0 345 *
nuclear@0 346 * Some flags are mutually exclusive, others are probably
nuclear@0 347 * not available because your excluded them from your
nuclear@0 348 * Assimp builds. Calling this function is recommended if
nuclear@0 349 * you're unsure.
nuclear@0 350 *
nuclear@0 351 * @param pFlags Bitwise combination of the aiPostProcess flags.
nuclear@0 352 * @return true if this flag combination is fine.
nuclear@0 353 */
nuclear@0 354 bool ValidateFlags(unsigned int pFlags) const;
nuclear@0 355
nuclear@0 356 // -------------------------------------------------------------------
nuclear@0 357 /** Reads the given file and returns its contents if successful.
nuclear@0 358 *
nuclear@0 359 * If the call succeeds, the contents of the file are returned as a
nuclear@0 360 * pointer to an aiScene object. The returned data is intended to be
nuclear@0 361 * read-only, the importer object keeps ownership of the data and will
nuclear@0 362 * destroy it upon destruction. If the import fails, NULL is returned.
nuclear@0 363 * A human-readable error description can be retrieved by calling
nuclear@0 364 * GetErrorString(). The previous scene will be deleted during this call.
nuclear@0 365 * @param pFile Path and filename to the file to be imported.
nuclear@0 366 * @param pFlags Optional post processing steps to be executed after
nuclear@0 367 * a successful import. Provide a bitwise combination of the
nuclear@0 368 * #aiPostProcessSteps flags. If you wish to inspect the imported
nuclear@0 369 * scene first in order to fine-tune your post-processing setup,
nuclear@0 370 * consider to use #ApplyPostProcessing().
nuclear@0 371 * @return A pointer to the imported data, NULL if the import failed.
nuclear@0 372 * The pointer to the scene remains in possession of the Importer
nuclear@0 373 * instance. Use GetOrphanedScene() to take ownership of it.
nuclear@0 374 *
nuclear@0 375 * @note Assimp is able to determine the file format of a file
nuclear@0 376 * automatically.
nuclear@0 377 */
nuclear@0 378 const aiScene* ReadFile(
nuclear@0 379 const char* pFile,
nuclear@0 380 unsigned int pFlags);
nuclear@0 381
nuclear@0 382 // -------------------------------------------------------------------
nuclear@0 383 /** Reads the given file from a memory buffer and returns its
nuclear@0 384 * contents if successful.
nuclear@0 385 *
nuclear@0 386 * If the call succeeds, the contents of the file are returned as a
nuclear@0 387 * pointer to an aiScene object. The returned data is intended to be
nuclear@0 388 * read-only, the importer object keeps ownership of the data and will
nuclear@0 389 * destroy it upon destruction. If the import fails, NULL is returned.
nuclear@0 390 * A human-readable error description can be retrieved by calling
nuclear@0 391 * GetErrorString(). The previous scene will be deleted during this call.
nuclear@0 392 * Calling this method doesn't affect the active IOSystem.
nuclear@0 393 * @param pBuffer Pointer to the file data
nuclear@0 394 * @param pLength Length of pBuffer, in bytes
nuclear@0 395 * @param pFlags Optional post processing steps to be executed after
nuclear@0 396 * a successful import. Provide a bitwise combination of the
nuclear@0 397 * #aiPostProcessSteps flags. If you wish to inspect the imported
nuclear@0 398 * scene first in order to fine-tune your post-processing setup,
nuclear@0 399 * consider to use #ApplyPostProcessing().
nuclear@0 400 * @param pHint An additional hint to the library. If this is a non
nuclear@0 401 * empty string, the library looks for a loader to support
nuclear@0 402 * the file extension specified by pHint and passes the file to
nuclear@0 403 * the first matching loader. If this loader is unable to completely
nuclear@0 404 * the request, the library continues and tries to determine the
nuclear@0 405 * file format on its own, a task that may or may not be successful.
nuclear@0 406 * Check the return value, and you'll know ...
nuclear@0 407 * @return A pointer to the imported data, NULL if the import failed.
nuclear@0 408 * The pointer to the scene remains in possession of the Importer
nuclear@0 409 * instance. Use GetOrphanedScene() to take ownership of it.
nuclear@0 410 *
nuclear@0 411 * @note This is a straightforward way to decode models from memory
nuclear@0 412 * buffers, but it doesn't handle model formats that spread their
nuclear@0 413 * data across multiple files or even directories. Examples include
nuclear@0 414 * OBJ or MD3, which outsource parts of their material info into
nuclear@0 415 * external scripts. If you need full functionality, provide
nuclear@0 416 * a custom IOSystem to make Assimp find these files and use
nuclear@0 417 * the regular ReadFile() API.
nuclear@0 418 */
nuclear@0 419 const aiScene* ReadFileFromMemory(
nuclear@0 420 const void* pBuffer,
nuclear@0 421 size_t pLength,
nuclear@0 422 unsigned int pFlags,
nuclear@0 423 const char* pHint = "");
nuclear@0 424
nuclear@0 425 // -------------------------------------------------------------------
nuclear@0 426 /** Apply post-processing to an already-imported scene.
nuclear@0 427 *
nuclear@0 428 * This is strictly equivalent to calling #ReadFile() with the same
nuclear@0 429 * flags. However, you can use this separate function to inspect
nuclear@0 430 * the imported scene first to fine-tune your post-processing setup.
nuclear@0 431 * @param pFlags Provide a bitwise combination of the
nuclear@0 432 * #aiPostProcessSteps flags.
nuclear@0 433 * @return A pointer to the post-processed data. This is still the
nuclear@0 434 * same as the pointer returned by #ReadFile(). However, if
nuclear@0 435 * post-processing fails, the scene could now be NULL.
nuclear@0 436 * That's quite a rare case, post processing steps are not really
nuclear@0 437 * designed to 'fail'. To be exact, the #aiProcess_ValidateDS
nuclear@0 438 * flag is currently the only post processing step which can actually
nuclear@0 439 * cause the scene to be reset to NULL.
nuclear@0 440 *
nuclear@0 441 * @note The method does nothing if no scene is currently bound
nuclear@0 442 * to the #Importer instance. */
nuclear@0 443 const aiScene* ApplyPostProcessing(unsigned int pFlags);
nuclear@0 444
nuclear@0 445 // -------------------------------------------------------------------
nuclear@0 446 /** @brief Reads the given file and returns its contents if successful.
nuclear@0 447 *
nuclear@0 448 * This function is provided for backward compatibility.
nuclear@0 449 * See the const char* version for detailled docs.
nuclear@0 450 * @see ReadFile(const char*, pFlags) */
nuclear@0 451 const aiScene* ReadFile(
nuclear@0 452 const std::string& pFile,
nuclear@0 453 unsigned int pFlags);
nuclear@0 454
nuclear@0 455 // -------------------------------------------------------------------
nuclear@0 456 /** Frees the current scene.
nuclear@0 457 *
nuclear@0 458 * The function does nothing if no scene has previously been
nuclear@0 459 * read via ReadFile(). FreeScene() is called automatically by the
nuclear@0 460 * destructor and ReadFile() itself. */
nuclear@0 461 void FreeScene( );
nuclear@0 462
nuclear@0 463 // -------------------------------------------------------------------
nuclear@0 464 /** Returns an error description of an error that occurred in ReadFile().
nuclear@0 465 *
nuclear@0 466 * Returns an empty string if no error occurred.
nuclear@0 467 * @return A description of the last error, an empty string if no
nuclear@0 468 * error occurred. The string is never NULL.
nuclear@0 469 *
nuclear@0 470 * @note The returned function remains valid until one of the
nuclear@0 471 * following methods is called: #ReadFile(), #FreeScene(). */
nuclear@0 472 const char* GetErrorString() const;
nuclear@0 473
nuclear@0 474 // -------------------------------------------------------------------
nuclear@0 475 /** Returns the scene loaded by the last successful call to ReadFile()
nuclear@0 476 *
nuclear@0 477 * @return Current scene or NULL if there is currently no scene loaded */
nuclear@0 478 const aiScene* GetScene() const;
nuclear@0 479
nuclear@0 480 // -------------------------------------------------------------------
nuclear@0 481 /** Returns the scene loaded by the last successful call to ReadFile()
nuclear@0 482 * and releases the scene from the ownership of the Importer
nuclear@0 483 * instance. The application is now responsible for deleting the
nuclear@0 484 * scene. Any further calls to GetScene() or GetOrphanedScene()
nuclear@0 485 * will return NULL - until a new scene has been loaded via ReadFile().
nuclear@0 486 *
nuclear@0 487 * @return Current scene or NULL if there is currently no scene loaded
nuclear@0 488 * @note Use this method with maximal caution, and only if you have to.
nuclear@0 489 * By design, aiScene's are exclusively maintained, allocated and
nuclear@0 490 * deallocated by Assimp and no one else. The reasoning behind this
nuclear@0 491 * is the golden rule that deallocations should always be done
nuclear@0 492 * by the module that did the original allocation because heaps
nuclear@0 493 * are not necessarily shared. GetOrphanedScene() enforces you
nuclear@0 494 * to delete the returned scene by yourself, but this will only
nuclear@0 495 * be fine if and only if you're using the same heap as assimp.
nuclear@0 496 * On Windows, it's typically fine provided everything is linked
nuclear@0 497 * against the multithreaded-dll version of the runtime library.
nuclear@0 498 * It will work as well for static linkage with Assimp.*/
nuclear@0 499 aiScene* GetOrphanedScene();
nuclear@0 500
nuclear@0 501
nuclear@0 502
nuclear@0 503
nuclear@0 504 // -------------------------------------------------------------------
nuclear@0 505 /** Returns whether a given file extension is supported by ASSIMP.
nuclear@0 506 *
nuclear@0 507 * @param szExtension Extension to be checked.
nuclear@0 508 * Must include a trailing dot '.'. Example: ".3ds", ".md3".
nuclear@0 509 * Cases-insensitive.
nuclear@0 510 * @return true if the extension is supported, false otherwise */
nuclear@0 511 bool IsExtensionSupported(const char* szExtension) const;
nuclear@0 512
nuclear@0 513 // -------------------------------------------------------------------
nuclear@0 514 /** @brief Returns whether a given file extension is supported by ASSIMP.
nuclear@0 515 *
nuclear@0 516 * This function is provided for backward compatibility.
nuclear@0 517 * See the const char* version for detailed and up-to-date docs.
nuclear@0 518 * @see IsExtensionSupported(const char*) */
nuclear@0 519 inline bool IsExtensionSupported(const std::string& szExtension) const;
nuclear@0 520
nuclear@0 521 // -------------------------------------------------------------------
nuclear@0 522 /** Get a full list of all file extensions supported by ASSIMP.
nuclear@0 523 *
nuclear@0 524 * If a file extension is contained in the list this does of course not
nuclear@0 525 * mean that ASSIMP is able to load all files with this extension ---
nuclear@0 526 * it simply means there is an importer loaded which claims to handle
nuclear@0 527 * files with this file extension.
nuclear@0 528 * @param szOut String to receive the extension list.
nuclear@0 529 * Format of the list: "*.3ds;*.obj;*.dae". This is useful for
nuclear@0 530 * use with the WinAPI call GetOpenFileName(Ex). */
nuclear@0 531 void GetExtensionList(aiString& szOut) const;
nuclear@0 532
nuclear@0 533 // -------------------------------------------------------------------
nuclear@0 534 /** @brief Get a full list of all file extensions supported by ASSIMP.
nuclear@0 535 *
nuclear@0 536 * This function is provided for backward compatibility.
nuclear@0 537 * See the aiString version for detailed and up-to-date docs.
nuclear@0 538 * @see GetExtensionList(aiString&)*/
nuclear@0 539 inline void GetExtensionList(std::string& szOut) const;
nuclear@0 540
nuclear@0 541 // -------------------------------------------------------------------
nuclear@0 542 /** Get the number of importrs currently registered with Assimp. */
nuclear@0 543 size_t GetImporterCount() const;
nuclear@0 544
nuclear@0 545 // -------------------------------------------------------------------
nuclear@0 546 /** Get meta data for the importer corresponding to a specific index..
nuclear@0 547 *
nuclear@0 548 * For the declaration of #aiImporterDesc, include <assimp/importerdesc.h>.
nuclear@0 549 * @param index Index to query, must be within [0,GetImporterCount())
nuclear@0 550 * @return Importer meta data structure, NULL if the index does not
nuclear@0 551 * exist or if the importer doesn't offer meta information (
nuclear@0 552 * importers may do this at the cost of being hated by their peers).*/
nuclear@0 553 const aiImporterDesc* GetImporterInfo(size_t index) const;
nuclear@0 554
nuclear@0 555 // -------------------------------------------------------------------
nuclear@0 556 /** Find the importer corresponding to a specific index.
nuclear@0 557 *
nuclear@0 558 * @param index Index to query, must be within [0,GetImporterCount())
nuclear@0 559 * @return Importer instance. NULL if the index does not
nuclear@0 560 * exist. */
nuclear@0 561 BaseImporter* GetImporter(size_t index) const;
nuclear@0 562
nuclear@0 563 // -------------------------------------------------------------------
nuclear@0 564 /** Find the importer corresponding to a specific file extension.
nuclear@0 565 *
nuclear@0 566 * This is quite similar to #IsExtensionSupported except a
nuclear@0 567 * BaseImporter instance is returned.
nuclear@0 568 * @param szExtension Extension to check for. The following formats
nuclear@0 569 * are recognized (BAH being the file extension): "BAH" (comparison
nuclear@0 570 * is case-insensitive), ".bah", "*.bah" (wild card and dot
nuclear@0 571 * characters at the beginning of the extension are skipped).
nuclear@0 572 * @return NULL if no importer is found*/
nuclear@0 573 BaseImporter* GetImporter (const char* szExtension) const;
nuclear@0 574
nuclear@0 575 // -------------------------------------------------------------------
nuclear@0 576 /** Find the importer index corresponding to a specific file extension.
nuclear@0 577 *
nuclear@0 578 * @param szExtension Extension to check for. The following formats
nuclear@0 579 * are recognized (BAH being the file extension): "BAH" (comparison
nuclear@0 580 * is case-insensitive), ".bah", "*.bah" (wild card and dot
nuclear@0 581 * characters at the beginning of the extension are skipped).
nuclear@0 582 * @return (size_t)-1 if no importer is found */
nuclear@0 583 size_t GetImporterIndex (const char* szExtension) const;
nuclear@0 584
nuclear@0 585
nuclear@0 586
nuclear@0 587
nuclear@0 588 // -------------------------------------------------------------------
nuclear@0 589 /** Returns the storage allocated by ASSIMP to hold the scene data
nuclear@0 590 * in memory.
nuclear@0 591 *
nuclear@0 592 * This refers to the currently loaded file, see #ReadFile().
nuclear@0 593 * @param in Data structure to be filled.
nuclear@0 594 * @note The returned memory statistics refer to the actual
nuclear@0 595 * size of the use data of the aiScene. Heap-related overhead
nuclear@0 596 * is (naturally) not included.*/
nuclear@0 597 void GetMemoryRequirements(aiMemoryInfo& in) const;
nuclear@0 598
nuclear@0 599 // -------------------------------------------------------------------
nuclear@0 600 /** Enables "extra verbose" mode.
nuclear@0 601 *
nuclear@0 602 * 'Extra verbose' means the data structure is validated after *every*
nuclear@0 603 * single post processing step to make sure everyone modifies the data
nuclear@0 604 * structure in a well-defined manner. This is a debug feature and not
nuclear@0 605 * intended for use in production environments. */
nuclear@0 606 void SetExtraVerbose(bool bDo);
nuclear@0 607
nuclear@0 608
nuclear@0 609 // -------------------------------------------------------------------
nuclear@0 610 /** Private, do not use. */
nuclear@0 611 ImporterPimpl* Pimpl() { return pimpl; };
nuclear@0 612 const ImporterPimpl* Pimpl() const { return pimpl; };
nuclear@0 613
nuclear@0 614 protected:
nuclear@0 615
nuclear@0 616 // Just because we don't want you to know how we're hacking around.
nuclear@0 617 ImporterPimpl* pimpl;
nuclear@0 618 }; //! class Importer
nuclear@0 619
nuclear@0 620
nuclear@0 621 // ----------------------------------------------------------------------------
nuclear@0 622 // For compatibility, the interface of some functions taking a std::string was
nuclear@0 623 // changed to const char* to avoid crashes between binary incompatible STL
nuclear@0 624 // versions. This code her is inlined, so it shouldn't cause any problems.
nuclear@0 625 // ----------------------------------------------------------------------------
nuclear@0 626
nuclear@0 627 // ----------------------------------------------------------------------------
nuclear@0 628 AI_FORCE_INLINE const aiScene* Importer::ReadFile( const std::string& pFile,unsigned int pFlags){
nuclear@0 629 return ReadFile(pFile.c_str(),pFlags);
nuclear@0 630 }
nuclear@0 631 // ----------------------------------------------------------------------------
nuclear@0 632 AI_FORCE_INLINE void Importer::GetExtensionList(std::string& szOut) const {
nuclear@0 633 aiString s;
nuclear@0 634 GetExtensionList(s);
nuclear@0 635 szOut = s.data;
nuclear@0 636 }
nuclear@0 637 // ----------------------------------------------------------------------------
nuclear@0 638 AI_FORCE_INLINE bool Importer::IsExtensionSupported(const std::string& szExtension) const {
nuclear@0 639 return IsExtensionSupported(szExtension.c_str());
nuclear@0 640 }
nuclear@0 641
nuclear@0 642 } // !namespace Assimp
nuclear@0 643 #endif // INCLUDED_AI_ASSIMP_HPP