diff --git a/code/BaseImporter.h b/code/BaseImporter.h index 0409b90b1..a4b9ce299 100644 --- a/code/BaseImporter.h +++ b/code/BaseImporter.h @@ -57,7 +57,8 @@ class Importer; (string[1] << 16) + (string[2] << 8) + string[3])) // --------------------------------------------------------------------------- -/** Simple exception class to be thrown if an error occurs while importing. */ +/** FOR IMPORTER PLUGINS ONLY: Simple exception class to be thrown if an + * error occurs while importing. */ class ASSIMP_API ImportErrorException { public: @@ -76,14 +77,14 @@ private: std::string mErrorText; }; +//! @cond never // --------------------------------------------------------------------------- /** @brief Internal PIMPL implementation for Assimp::Importer * * Using this idiom here allows us to drop the dependency from * std::vector and std::map in the public headers. Furthermore we are dropping * any STL interface problems caused by mismatching STL settings. All - * size calculation are now done by us, not the app heap. - */ + * size calculation are now done by us, not the app heap. */ class ASSIMP_API ImporterPimpl { public: @@ -131,10 +132,11 @@ public: /** Used by post-process steps to share data */ SharedPostProcessInfo* mPPShared; }; +//! @endcond // --------------------------------------------------------------------------- -/** The BaseImporter defines a common interface for all importer worker - * classes. +/** FOR IMPORTER PLUGINS ONLY: The BaseImporter defines a common interface + * for all importer worker classes. * * The interface defines two functions: CanRead() is used to check if the * importer can handle the format of the given file. If an implementation of @@ -372,25 +374,23 @@ protected: struct BatchData; // --------------------------------------------------------------------------- -/** A helper class that can be used by importers which need to load many - * extern meshes recursively. +/** FOR IMPORTER PLUGINS ONLY: A helper class for the pleasure of importers + * which need to load many extern meshes recursively. * * The class uses several threads to load these meshes (or at least it * could, this has not yet been implemented at the moment). * - * @note The class may not be used by more than one thread - */ + * @note The class may not be used by more than one thread*/ class ASSIMP_API BatchLoader { // friend of Importer public: - /** Represents a full list of configuration properties - * for the importer. - * - * Properties can be set using SetGenericProperty - */ + //! @cond never + // ------------------------------------------------------------------- + /** Wraps a full list of configuration properties for an importer. + * Properties can be set using SetGenericProperty */ struct PropertyMap { ImporterPimpl::IntPropertyMap ints; @@ -406,43 +406,40 @@ public: return ints.empty() && floats.empty() && strings.empty(); } }; + //! @endcond public: - /** Construct a batch loader from a given IO system - */ + // ------------------------------------------------------------------- + /** Construct a batch loader from a given IO system to be used to acess external files */ BatchLoader(IOSystem* pIO); ~BatchLoader(); - + // ------------------------------------------------------------------- /** Add a new file to the list of files to be loaded. - * * @param file File to be loaded - * @param steps Steps to be executed on the file + * @param steps Post-processing steps to be executed on the file * @param map Optional configuration properties * @return 'Load request channel' - an unique ID that can later * be used to access the imported file data. - */ + * @see GetImport */ unsigned int AddLoadRequest (const std::string& file, unsigned int steps = 0, const PropertyMap* map = NULL); - + // ------------------------------------------------------------------- /** Get an imported scene. - * * This polls the import from the internal request list. * If an import is requested several times, this function * can be called several times, too. * * @param which LRWC returned by AddLoadRequest(). * @return NULL if there is no scene with this file name - * in the queue of the scene hasn't been loaded yet. - */ - aiScene* GetImport (unsigned int which); + * in the queue of the scene hasn't been loaded yet. */ + aiScene* GetImport (unsigned int which); - - /** Waits until all scenes have been loaded. - */ + // ------------------------------------------------------------------- + /** Waits until all scenes have been loaded. */ void LoadAll(); private: diff --git a/code/Importer.cpp b/code/Importer.cpp index 5d6410b80..b9430c454 100644 --- a/code/Importer.cpp +++ b/code/Importer.cpp @@ -69,6 +69,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // ....................................................................................... // Importers +// (include_new_importers_here) // ....................................................................................... #ifndef AI_BUILD_NO_X_IMPORTER # include "XFileImporter.h" @@ -269,8 +270,7 @@ Importer::Importer() // ---------------------------------------------------------------------------- // Add an instance of each worker class here - // The order doesn't really care. File formats that are - // used more frequently than others should be at the beginning. + // (register_new_importers_here) // ---------------------------------------------------------------------------- pimpl->mImporter.reserve(25); #if (!defined AI_BUILD_NO_X_IMPORTER) diff --git a/code/irrXMLWrapper.h b/code/irrXMLWrapper.h index 4ec2fe3ff..57c5ed5c5 100644 --- a/code/irrXMLWrapper.h +++ b/code/irrXMLWrapper.h @@ -48,7 +48,24 @@ namespace Assimp { // --------------------------------------------------------------------------------- /** @brief Utility class to make IrrXML work together with our custom IO system - * See the IrrXML docs for more details.*/ + * See the IrrXML docs for more details. + * + * Construct IrrXML-Reader in BaseImporter::InternReadFile(): + * @code + * // open the file + * boost::scoped_ptr file( pIOHandler->Open( pFile)); + * if( file.get() == NULL) { + * throw new ImportErrorException( "Failed to open file " + pFile + "."); + * } + * + * // generate a XML reader for it + * boost::scoped_ptr mIOWrapper( new CIrrXML_IOStreamReader( file.get())); + * mReader = irr::io::createIrrXMLReader( mIOWrapper.get()); + * if( !mReader) { + * ThrowException( "xxxx: Unable to open file."); + * } + * @endcode + **/ class CIrrXML_IOStreamReader : public irr::io::IFileReadCallBack { diff --git a/doc/AssimpDoc_Html/AssimpDoc.chm b/doc/AssimpDoc_Html/AssimpDoc.chm index babbc6760..68f62caab 100644 Binary files a/doc/AssimpDoc_Html/AssimpDoc.chm and b/doc/AssimpDoc_Html/AssimpDoc.chm differ diff --git a/doc/Doxyfile b/doc/Doxyfile index c9d290cc9..2a44c0a01 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -4,7 +4,7 @@ # Project related configuration options #--------------------------------------------------------------------------- DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = assimp +PROJECT_NAME = Assimp PROJECT_NUMBER = r400 OUTPUT_DIRECTORY = CREATE_SUBDIRS = NO @@ -96,7 +96,8 @@ WARN_LOGFILE = # configuration options related to the input files #--------------------------------------------------------------------------- INPUT = ../include/ \ - ../doc/dox.h + ../doc/dox.h \ + ../code/BaseImporter.h INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c \ *.cc \ diff --git a/doc/dox.h b/doc/dox.h index 6898153a2..40e3633a5 100644 --- a/doc/dox.h +++ b/doc/dox.h @@ -91,6 +91,13 @@ When the importer successfully completed its job, the imported data is returned point from where you can access all the various data types that a scene/model file can possibly contain. The @link data Data Structures page @endlink describes how to interpret this data. +@section ext Extending the library + +There are many 3d file formats in the world, and we're happy to support as many as possible. If you need support for +a particular file format, why not implement it yourself and add it to the library? Writing importer plugins for +ASSIMP is considerably easy, as the whole postprocessing infrastructure is available and does much of the work for you. +See the @link extend Extending the library @endlink page for more information. + @section main_viewer The Viewer The ASSIMP viewer is a standalone Windows/DirectX application that was developed along with the library. It is very useful @@ -759,6 +766,182 @@ contains the most common file extension of the embedded texture's format. This v set if ASSIMP is able to determine the file format. */ +/** +@page extend Extending the Library + +@section General + +Or - how to write your own loaders. It's easy. You just need to implement the #Assimp::BaseImporter class, +which defines a few abstract methods, register your loader, test it carefully, and provide test models for it. + +OK, that sounds too easy :-). The whole procedure for a new loader merely looks like this: + + + +@section tnote Notes for text importers + + + +@section bnote Notes for binary importers + + + +@section util Utilities + +Mixed stuff for internal use by loaders, mostly documented (most of them are already included by AssimpPCH.h): + + +@section mat Filling materials + +The required definitions zo set/remove/query keys in #aiMaterial structures are declared in MaterialSystem.h, in a +#aiMaterial derivate called #Assimp::MaterialHelper. The header is included by AssimpPCH.h, so you don't need to bother. + +@code +MaterialHelper* mat = new MaterialHelper(); + +const float spec = 16.f; +mat->AddProperty(&spec, 1, AI_MATKEY_SHININESS); +@endcode + +@section boost Boost + +The boost whitelist: + + +(if you happen to need something else, i.e. boost::thread, make this an optional feature. +ASSIMP_BUILD_BOOST_WORKAROUND is defined for -noboost builds) + +@section appa Appendix A - Template for BaseImporter's abstract methods + +@code +// ------------------------------------------------------------------------------- +// Returns whether the class can handle the format of the given file. +bool xxxxImporter::CanRead( const std::string& pFile, IOSystem* pIOHandler, + bool checkSig) const +{ + const std::string extension = GetExtension(pFile); + if(extension == "xxxx") { + return true; + } + if (!extension.length() || checkSig) { + // no extension given, or we're called a second time because no + // suitable loader was found yet. This means, we're trying to open + // the file and look for and hints to identify the file format. + // #Assimp::BaseImporter provides some utilities: + // + // #Assimp::BaseImporter::SearchFileHeaderForToken - for text files. + // It reads the first lines of the file and does a substring check + // against a given list of 'magic' strings. + // + // #Assimp::BaseImporter::CheckMagicToken - for binary files. It goes + // to a particular offset in the file and and compares the next words + // against a given list of 'magic' tokens. + + // These checks MUST be done (even if !checkSig) if the file extension + // is not exclusive to your format. For example, .xml is very common + // and (co)used by many formats. + } + return false; +} + +// ------------------------------------------------------------------------------- +// Get list of file extensions handled by this loader +void xxxxImporter::GetExtensionList(std::string& append) +{ + append.append("*.xxx"); +} + +// ------------------------------------------------------------------------------- +void xxxxImporter::InternReadFile( const std::string& pFile, + aiScene* pScene, IOSystem* pIOHandler) +{ + boost::scoped_ptr file( pIOHandler->Open( pFile, "rb")); + + // Check whether we can read from the file + if( file.get() == NULL) { + throw new ImportErrorException( "Failed to open xxxx file " + pFile + "."); + } + + // Your task: fill pScene + // Throw a ImportErrorException with a meaningful (!) error message if + // something goes wrong. +} + +@endcode + */ + /** @page materials Material System diff --git a/include/DefaultLogger.h b/include/DefaultLogger.h index 0f814aec6..3fdcb5a21 100644 --- a/include/DefaultLogger.h +++ b/include/DefaultLogger.h @@ -57,8 +57,7 @@ struct LogStreamInfo; #define ASSIMP_DEFAULT_LOG_NAME "AssimpLog.txt" // ------------------------------------------------------------------------------------ -/** @class DefaultLogger - * @brief Primary logging implementation of Assimp. +/** @brief CPP-API: Primary logging facility of Assimp. * * The library stores its primary #Logger as a static member of this class. * #get() returns this primary logger. By default the underlying implementation is @@ -69,10 +68,10 @@ struct LogStreamInfo; * * If you wish to customize the logging at an even deeper level supply your own * implementation of #Logger to #set(). - * @note The whole logging stuff causes a small extra overhead for all imports. - */ + * @note The whole logging stuff causes a small extra overhead for all imports. */ class ASSIMP_API DefaultLogger : public Logger { + public: // ---------------------------------------------------------------------- @@ -86,10 +85,7 @@ public: * passed for 'name', no log file is created at all. * @param io IOSystem to be used to open external files (such as the * log file). Pass NULL to rely on the default implementation. - * - * This replaces the default #NullLogger with a #DefaultLogger instance. - * @note You can't - */ + * This replaces the default #NullLogger with a #DefaultLogger instance. */ static Logger *create(const char* name = ASSIMP_DEFAULT_LOG_NAME, LogSeverity severity = NORMAL, unsigned int defStreams = aiDefaultLogStream_DEBUGGER | aiDefaultLogStream_FILE, @@ -102,40 +98,34 @@ public: * your needs. If the provided message formatting is OK for you, * it's much easier to use #create() and to attach your own custom * output streams to it. - * @param logger Pass NULL to setup a default NullLogger - */ + * @param logger Pass NULL to setup a default NullLogger*/ static void set (Logger *logger); // ---------------------------------------------------------------------- /** @brief Getter for singleton instance * @return Only instance. This is never null, but it could be a - * NullLogger. Use isNullLogger to check this. - */ + * NullLogger. Use isNullLogger to check this.*/ static Logger *get(); // ---------------------------------------------------------------------- /** @brief Return whether a #NullLogger is currently active * @return true if the current logger is a #NullLogger. * Use create() or set() to setup a logger that does actually do - * something else than just rejecting all log messages. - */ + * something else than just rejecting all log messages. */ static bool isNullLogger(); // ---------------------------------------------------------------------- /** @brief Kills the current singleton logger and replaces it with a - * #NullLogger instance. - */ + * #NullLogger instance. */ static void kill(); // ---------------------------------------------------------------------- - /** @copydoc Logger::attachStream - */ + /** @copydoc Logger::attachStream */ bool attachStream(LogStream *pStream, unsigned int severity); // ---------------------------------------------------------------------- - /** @copydoc Logger::detatchStream - */ + /** @copydoc Logger::detatchStream */ bool detatchStream(LogStream *pStream, unsigned int severity); @@ -144,8 +134,7 @@ private: // ---------------------------------------------------------------------- /** @briefPrivate construction for internal use by create(). - * @param severity Logging granularity - */ + * @param severity Logging granularity */ DefaultLogger(LogSeverity severity); // ---------------------------------------------------------------------- diff --git a/include/IOStream.h b/include/IOStream.h index 06977b167..968a7e87c 100644 --- a/include/IOStream.h +++ b/include/IOStream.h @@ -55,8 +55,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. namespace Assimp { // ---------------------------------------------------------------------------------- -/** @class IOStream - * @brief Class to handle file I/O for C++ +/** @brief CPP-API: Class to handle file I/O for C++ * * Derive an own implementation from this interface to provide custom IO handling * to the Importer. If you implement this interface, be sure to also provide an diff --git a/include/IOSystem.h b/include/IOSystem.h index a85cd1808..8872f239f 100644 --- a/include/IOSystem.h +++ b/include/IOSystem.h @@ -57,15 +57,13 @@ namespace Assimp { class IOStream; // --------------------------------------------------------------------------- -/** @class IOSystem - * @brief Interface to the file system. +/** @brief CPP-API: Interface to the file system. * * Derive an own implementation from this interface to supply custom file handling * to the importer library. If you implement this interface, you also want to * supply a custom implementation for IOStream. * - * @see Importer::SetIOHandler() - */ + * @see Importer::SetIOHandler() */ class ASSIMP_API IOSystem : public Intern::AllocateFromAssimpHeap { public: diff --git a/include/LogStream.h b/include/LogStream.h index 670c0747e..041b0f085 100644 --- a/include/LogStream.h +++ b/include/LogStream.h @@ -41,7 +41,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /** @file LogStream.h * @brief Abstract base class 'LogStream', representing an output log stream. */ - #ifndef INCLUDED_AI_LOGSTREAM_H #define INCLUDED_AI_LOGSTREAM_H #include "aiTypes.h" @@ -49,13 +48,11 @@ namespace Assimp { class IOSystem; // ------------------------------------------------------------------------------------ -/** @class LogStream - * @brief Abstract interface for log stream implementations. +/** @brief CPP-API: Abstract interface for log stream implementations. * * Several default implementations are provided, see #aiDefaultLogStream for more * details. Writing your own implementation of LogStream is just necessary if these - * are not enough for your purposes. - */ + * are not enough for your purpose. */ class ASSIMP_API LogStream : public Intern::AllocateFromAssimpHeap { protected: @@ -75,8 +72,7 @@ public: * (e.g. generate HTML), supply a custom instance of Logger to * #DefaultLogger:set(). Usually you can *expect* that a log message * is exactly one line and terminated with a single \n character. - * @param message Message to be written - */ + * @param message Message to be written */ virtual void write(const char* message) = 0; // ------------------------------------------------------------------- @@ -85,8 +81,7 @@ public: * @param name For aiDefaultLogStream_FILE: name of the output file * @param io For aiDefaultLogStream_FILE: IOSystem to be used to open the output * file. Pass NULL for the default implementation. - * @return New LogStream instance. - */ + * @return New LogStream instance. */ static LogStream* createDefaultStream(aiDefaultLogStream stream, const char* name = "AssimpLog.txt", IOSystem* io = NULL); diff --git a/include/Logger.h b/include/Logger.h index 0ece1ec49..04b90281e 100644 --- a/include/Logger.h +++ b/include/Logger.h @@ -52,15 +52,12 @@ class LogStream; #define MAX_LOG_MESSAGE_LENGTH 1024u // ---------------------------------------------------------------------------------- -/** @class Logger - * @brief Abstract interface for logger implementations. +/** @brief CPP-API: Abstract interface for logger implementations. * Assimp provides a default implementation and uses it for almost all * logging stuff ('DefaultLogger'). This class defines just basic logging - * behaviour and is not of interest for you. - */ + * behaviour and is not of interest for you. Instead, take a look at #DefaultLogger. */ class ASSIMP_API Logger - : public Intern::AllocateFromAssimpHeap -{ + : public Intern::AllocateFromAssimpHeap { public: // ---------------------------------------------------------------------- @@ -96,37 +93,31 @@ public: // ---------------------------------------------------------------------- /** @brief Writes a debug message - * @param message Debug message - */ + * @param message Debug message*/ void debug(const std::string &message); // ---------------------------------------------------------------------- /** @brief Writes a info message - * @param message Info message - */ + * @param message Info message*/ void info(const std::string &message); // ---------------------------------------------------------------------- /** @brief Writes a warning message - * @param message Warn message - */ + * @param message Warn message*/ void warn(const std::string &message); // ---------------------------------------------------------------------- /** @brief Writes an error message - * @param message Error message - */ + * @param message Error message*/ void error(const std::string &message); // ---------------------------------------------------------------------- /** @brief Set a new log severity. - * @param log_severity New severity for logging - */ + * @param log_severity New severity for logging*/ void setLogSeverity(LogSeverity log_severity); // ---------------------------------------------------------------------- - /** @brief Get the current log severity - */ + /** @brief Get the current log severity*/ LogSeverity getLogSeverity() const; // ---------------------------------------------------------------------- @@ -140,8 +131,7 @@ public: * @param severity Message filter, specified which types of log * messages are dispatched to the stream. Provide a bitwise * combination of the ErrorSeverity flags. - * @return true if the stream has been attached, false otherwise. - */ + * @return true if the stream has been attached, false otherwise.*/ virtual bool attachStream(LogStream *pStream, unsigned int severity = DEBUGGING | ERR | WARN | INFO) = 0; @@ -153,8 +143,7 @@ public: * flags. This value is &~ed with the current flags of the stream, * if the result is 0 the stream is detached from the Logger and * the caller retakes the possession of the stream. - * @return true if the stream has been dettached, false otherwise. - */ + * @return true if the stream has been dettached, false otherwise.*/ virtual bool detatchStream(LogStream *pStream, unsigned int severity = DEBUGGING | ERR | WARN | INFO) = 0; diff --git a/include/NullLogger.h b/include/NullLogger.h index f1fb95a05..e1f5802d2 100644 --- a/include/NullLogger.h +++ b/include/NullLogger.h @@ -48,14 +48,13 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. #include "Logger.h" namespace Assimp { // --------------------------------------------------------------------------- -/** @class NullLogger - * @brief Empty logging implementation. +/** @brief CPP-API: Empty logging implementation. * - * Does nothing. Used by default if the application hasn't requested a - * custom logger via #DefaultLogger::set() or #DefaultLogger::create(); - */ -class ASSIMP_API NullLogger : public Logger -{ + * Does nothing! Used by default if the application hasn't requested a + * custom logger via #DefaultLogger::set() or #DefaultLogger::create(); */ +class ASSIMP_API NullLogger + : public Logger { + public: /** @brief Logs a debug message */ diff --git a/include/aiAnim.h b/include/aiAnim.h index 4084e711f..2ce4d2784 100644 --- a/include/aiAnim.h +++ b/include/aiAnim.h @@ -143,35 +143,29 @@ struct aiQuatKey // --------------------------------------------------------------------------- /** Defines how an animation channel behaves outside the defined time * range. This corresponds to aiNodeAnim::mPreState and - * aiNodeAnim::mPostState. - */ + * aiNodeAnim::mPostState.*/ enum aiAnimBehaviour { - /** The value from the default node transformation is taken - */ + /** The value from the default node transformation is taken*/ aiAnimBehaviour_DEFAULT = 0x0, - /** The nearest key value is used without interpolation - */ + /** The nearest key value is used without interpolation */ aiAnimBehaviour_CONSTANT = 0x1, /** The value of the nearest two keys is linearly - * extrapolated for the current time value. - */ + * extrapolated for the current time value.*/ aiAnimBehaviour_LINEAR = 0x2, /** The animation is repeated. * * If the animation key go from n to m and the current - * time is t, use the value at (t-n) % (|m-n|). - */ + * time is t, use the value at (t-n) % (|m-n|).*/ aiAnimBehaviour_REPEAT = 0x3, /** This value is not used, it is just here to force the - * the compiler to map this enum to a 32 Bit integer - */ + * the compiler to map this enum to a 32 Bit integer */ _aiAnimBehaviour_Force32Bit = 0x8fffffff }; @@ -187,13 +181,11 @@ enum aiAnimBehaviour * @note All keys are returned in their correct, chronological order. * Duplicate keys don't pass the validation step. Most likely there * will be no negative time values, but they are not forbidden ( so you should - * be able to handle them ) - */ + * be able to handle them ) */ struct aiNodeAnim { /** The name of the node affected by this animation. The node - * must exist and it must be unique. - */ + * must exist and it must be unique.*/ C_STRUCT aiString mNodeName; /** The number of position keys */ @@ -203,8 +195,7 @@ struct aiNodeAnim * specified as 3D vector. The array is mNumPositionKeys in size. * * If there are position keys, there will also be at least one - * scaling and one rotation key. - */ + * scaling and one rotation key.*/ C_STRUCT aiVectorKey* mPositionKeys; /** The number of rotation keys */ @@ -215,8 +206,7 @@ struct aiNodeAnim * mNumRotationKeys in size. * * If there are rotation keys, there will also be at least one - * scaling and one position key. - */ + * scaling and one position key. */ C_STRUCT aiQuatKey* mRotationKeys; @@ -227,8 +217,7 @@ struct aiNodeAnim * specified as 3D vector. The array is mNumScalingKeys in size. * * If there are scaling keys, there will also be at least one - * position and one rotation key. - */ + * position and one rotation key.*/ C_STRUCT aiVectorKey* mScalingKeys; @@ -236,16 +225,14 @@ struct aiNodeAnim * key is encountered. * * The default value is aiAnimBehaviour_DEFAULT (the original - * transformation matrix of the affected node is used). - */ + * transformation matrix of the affected node is used).*/ C_ENUM aiAnimBehaviour mPreState; /** Defines how the animation behaves after the last * key was processed. * * The default value is aiAnimBehaviour_DEFAULT (the original - * transformation matrix of the affected node is taken). - */ + * transformation matrix of the affected node is taken).*/ C_ENUM aiAnimBehaviour mPostState; #ifdef __cplusplus @@ -269,32 +256,26 @@ struct aiNodeAnim // --------------------------------------------------------------------------- /** An animation consists of keyframe data for a number of nodes. For - * each node affected by the animation a separate series of data is given. - */ + * each node affected by the animation a separate series of data is given.*/ struct aiAnimation { /** The name of the animation. If the modeling package this data was * exported from does support only a single animation channel, this - * name is usually empty (length is zero). - */ + * name is usually empty (length is zero). */ C_STRUCT aiString mName; - /** Duration of the animation in ticks. - */ + /** Duration of the animation in ticks. */ double mDuration; - /** Ticks per second. 0 if not specified in the imported file - */ + /** Ticks per second. 0 if not specified in the imported file */ double mTicksPerSecond; /** The number of bone animation channels. Each channel affects - * a single node. - */ + * a single node. */ unsigned int mNumChannels; /** The node animation channels. Each channel affects a single node. - * The array is mNumChannels in size. - */ + * The array is mNumChannels in size. */ C_STRUCT aiNodeAnim** mChannels; #ifdef __cplusplus @@ -326,13 +307,11 @@ struct aiAnimation // some C++ utilities for inter- and extrapolation namespace Assimp { - // --------------------------------------------------------------------------- -/** @brief Utility class to simplify interpolations of various data types. +/** @brief CPP-API: Utility class to simplify interpolations of various data types. * * The type of interpolation is choosen automatically depending on the - * types of the arguments. - */ + * types of the arguments. */ template struct Interpolator { @@ -341,8 +320,7 @@ struct Interpolator * * The interpolation algorithm depends on the type of the operands. * aiQuaternion's and aiQuatKey's SLERP, the rest does a simple - * linear interpolation. - */ + * linear interpolation. */ void operator () (T& out,const T& a, const T& b, float d) const { out = a + (b-a)*d; } diff --git a/include/aiFileIO.h b/include/aiFileIO.h index bec7b7cc0..249a0d46d 100644 --- a/include/aiFileIO.h +++ b/include/aiFileIO.h @@ -67,13 +67,12 @@ typedef void (*aiFileCloseProc) (C_STRUCT aiFileIO*, C_STRUCT aiFile*); typedef char* aiUserData; // ---------------------------------------------------------------------------------- -/** @class aiFileIO - * @brief Defines Assimp's way of accessing files. +/** @brief C-API: File system callbacks * * Provided are functions to open and close files. Supply a custom structure to - * the import function. If you don't, a default implementation is used. Use this - * to enable reading from other sources, such as ZIPs or memory locations. -*/ + * the import function. If you don't, a default implementation is used. Use custom + * file systems to enable reading from other sources, such as ZIPs + * or memory locations. */ struct aiFileIO { /** Function used to open a new file @@ -89,17 +88,15 @@ struct aiFileIO }; // ---------------------------------------------------------------------------------- -/** @class aiFile - * @brief Represents a read/write file +/** @brief C-API: File callbacks * * Actually, it's a data structure to wrap a set of fXXXX (e.g fopen) - * replacement functions + * replacement functions. * * The default implementation of the functions utilizes the fXXX functions from * the CRT. However, you can supply a custom implementation to Assimp by * delivering a custom aiFileIO. Use this to enable reading from other sources, - * such as ZIP archives or memory locations. - */ + * such as ZIP archives or memory locations. */ struct aiFile { /** Callback to read from a file */ diff --git a/include/aiTypes.h b/include/aiTypes.h index c90261970..f604e31d3 100644 --- a/include/aiTypes.h +++ b/include/aiTypes.h @@ -65,8 +65,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # include // for aiString::Set(const std::string&) namespace Assimp { -namespace Intern { + //! @cond never +namespace Intern { // -------------------------------------------------------------------- /** @brief Internal helper class to utilize our internal new/delete * routines for allocating object of this and derived classes. @@ -90,9 +91,10 @@ namespace Intern { void *operator new[] ( size_t num_bytes); void operator delete[] ( void* data); - }; //! struct AllocateFromAssimpHeap -} //! namespace Intern -} //! namespace Assimp + }; // struct AllocateFromAssimpHeap +} // namespace Intern + //! @endcond +} // namespace Assimp extern "C" { #endif diff --git a/include/assimp.h b/include/assimp.h index 007992379..373d9030c 100644 --- a/include/assimp.h +++ b/include/assimp.h @@ -55,12 +55,11 @@ struct aiFileIO; // aiFileIO.h typedef void (*aiLogStreamCallback)(const char* /* message */, char* /* user */); // -------------------------------------------------------------------------------- -/** Represents a log stream. A log stream receives all log messages and streams - * them somewhere. +/** C-API: Represents a log stream. A log stream receives all log messages and + * streams them _somewhere_. * @see aiGetPredefinedLogStream * @see aiAttachLogStream - * @see aiDetachLogStream - */ + * @see aiDetachLogStream */ // -------------------------------------------------------------------------------- struct aiLogStream { diff --git a/include/assimp.hpp b/include/assimp.hpp index da60850c6..5ab9e2a2c 100644 --- a/include/assimp.hpp +++ b/include/assimp.hpp @@ -85,10 +85,11 @@ extern "C" ASSIMP_API const aiScene* aiImportFileEx( const char*, unsigned int, extern "C" ASSIMP_API const aiScene* aiImportFileFromMemory( const char*, unsigned int,unsigned int,const char*); +/** @namespace Assimp Assimp's CPP-API and all internal APIs */ namespace Assimp { // ---------------------------------------------------------------------------------- -/** The Importer class forms an C++ interface to the functionality of the +/** CPP-API: The Importer class forms an C++ interface to the functionality of the * Open Asset Import Library. * * Create an object of this class and call ReadFile() to import a file.