miniassimp

annotate include/miniassimp/Importer.hpp @ 0:879c81d94345

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