Doc now includes parts of the internal API.
Documenting importer plugin development. Cleaning up doxygen usage in the public API. git-svn-id: https://assimp.svn.sourceforge.net/svnroot/assimp/trunk@473 67173fc5-114c-0410-ac8e-9d2fd5bffc1fpull/1/head
aramis_acg
parent
a5d0829b78
commit
8929ee3da5
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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<IOStream> 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<CIrrXML_IOStreamReader> 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
|
||||
{
|
||||
|
|
|
|||
Binary file not shown.
|
|
@ -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 \
|
||||
|
|
|
|||
183
doc/dox.h
183
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:
|
||||
|
||||
<ul>
|
||||
<li>Create a header (<tt><i>FormatName</i>Importer.h</tt>) and a unit (<tt><i>FormatName</i>Importer.cpp</tt>) in the <tt><root>/code/</tt> directory</li>
|
||||
<li>Add them to the following workspaces: vc8, vc9, CMAKE</li>
|
||||
<li>Include <i>AssimpPCH.h</i> - this is the PCH file, and it includes already most Assimp-internal stuff. </li>
|
||||
<li>Open Importer.cpp and include your header just below the <i>(include_new_importers_here)</i> line,
|
||||
guarded by a #define
|
||||
@code
|
||||
#if (!defined ASSIMP_BUILD_NO_FormatName_IMPORTER)
|
||||
...
|
||||
#endif
|
||||
@endcode
|
||||
Wrap the same guard around your .cpp!</li>
|
||||
|
||||
<li>No advance to the <i>(register_new_importers_here)</i> line in the Importer.cpp and register your importer there - just like all the others do.</li>
|
||||
<li>Setup a suitable test environment (i.e. use AssimpView or your own application), make sure to enable
|
||||
the #aiProcess_ValidateDataStructure flag and enable verbose logging. That is, simply call before you import anything:
|
||||
@code
|
||||
DefaultLogger::create("AssimpLog.txt",Logger::VERBOSE)
|
||||
@endcode
|
||||
</li>
|
||||
<li>
|
||||
Implement the Assimp::BaseImporter::CanRead(), Assimp::BaseImporter::InternReadFile() and Assimp::BaseImporter::GetExtensionList().
|
||||
Just copy'n'paste the template from Appendix A and adapt it for your needs.
|
||||
</li>
|
||||
<li>
|
||||
Make sure the loader compiles against all build configurations on all supported platforms. This includes <i>-noboost</i>! To avoid problems,
|
||||
see the boost section on this page for a list of all 'allowed' boost classes (again, this grew historically when we had to accept that boost
|
||||
is not THAT widely spread that one could rely on it being available everywhere).
|
||||
</li>
|
||||
<li>
|
||||
Provide some _free_ test models in <tt><root>/test/models/<FormatName>/</tt> and credit their authors.
|
||||
Test files for a file format shouldn't be too large (<i>~500 KiB in total</i>), and not too repetive. Try to cover all format features with test data.
|
||||
</li>
|
||||
<li>
|
||||
Done! Please, share your loader that everyone can profit from it!
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@section tnote Notes for text importers
|
||||
|
||||
<ul>
|
||||
<li>Try to make your parser as flexible as possible. Don't rely on particular layout, whitespace/tab style,
|
||||
except if the file format has a strict definition.</li>
|
||||
<li>Call Assimp::BaseImporter::ConvertToUTF8() before you parse anything to convert foreign encodings to UTF-8.
|
||||
That's not necessary for XML importers, which must use the provided IrrXML for reading. </li>
|
||||
</ul>
|
||||
|
||||
@section bnote Notes for binary importers
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
Take care of endianess issues! Assimp importers mostly support big-endian platforms, which define the <tt>AI_BUILD_BIG_ENDIAN</tt> constant.
|
||||
See the next section for a list of utilities to simplify this task.
|
||||
</li>
|
||||
<li>
|
||||
Don't trust the input data! Check all offsets!
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@section util Utilities
|
||||
|
||||
Mixed stuff for internal use by loaders, mostly documented (most of them are already included by <i>AssimpPCH.h</i>):
|
||||
<ul>
|
||||
<li><b>ByteSwap</b> (<i>ByteSwap.h</i>) - manual byte swapping stuff for binary loaders.</li>
|
||||
<li><b>StreamReader</b> (<i>StreamReader.h</i>) - safe, endianess-correct, binary reading.</li>
|
||||
<li><b>IrrXML</b> (<i>irrXMLWrapper.h</i>) - for XML-parsing (SAX.</li>
|
||||
<li><b>CommentRemover</b> (<i>RemoveComments.h</i>) - remove single-line and multi-line comments from a text file.</li>
|
||||
<li>fast_atof, strtol10, strtol16, SkipSpaceAndLineEnd, SkipToNextToken .. large family of low-level
|
||||
parsing functions, mostly declared in <i>fast_atof.h</i>, <i>StringComparison.h</i> and <i>ParsingUtils.h</i> (a collection that grew
|
||||
historically, so don't expect perfect organization). </li>
|
||||
<li><b>ComputeNormalsWithSmoothingsGroups()</b> (<i>SmoothingGroups.h</i>) - Computes normal vectors from plain old smoothing groups. </li>
|
||||
<li><b>SkeletonMeshBuilder</b> (<i>SkeletonMeshBuilder.h</i>) - generate a dummy mesh from a given (animation) skeleton. </li>
|
||||
<li><b>StandardShapes</b> (<i>StandardShapes.h</i>) - generate meshes for standard solids, such as platonic primitives, cylinders or spheres. </li>
|
||||
<li><b>BatchLoader</b> (<i>BaseImporter.h</i>) - manage imports from external files. Useful for file formats
|
||||
which spread their data across multiple files. </li>
|
||||
<li><b>SceneCombiner</b> (<i>SceneCombiner.h</i>) - exhaustive toolset to merge multiple scenes. Useful for file formats
|
||||
which spread their data across multiple files. </li>
|
||||
</ul>
|
||||
|
||||
@section mat Filling materials
|
||||
|
||||
The required definitions zo set/remove/query keys in #aiMaterial structures are declared in <i>MaterialSystem.h</i>, 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:
|
||||
<ul>
|
||||
<li><i>boost.scoped_ptr</i></li>
|
||||
<li><i>boost.scoped_array</i></li>
|
||||
<li><i>boost.format</i> </li>
|
||||
<li><i>boost.random</i> </li>
|
||||
<li><i>boost.common_factor</i> </li>
|
||||
<li><i>boost.foreach</i> </li>
|
||||
<li><i>boost.tuple</i></li>
|
||||
</ul>
|
||||
|
||||
(if you happen to need something else, i.e. boost::thread, make this an optional feature.
|
||||
<tt>ASSIMP_BUILD_BOOST_WORKAROUND</tt> is defined for <i>-noboost</i> 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<IOStream> 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
||||
// ----------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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 */
|
||||
|
|
|
|||
|
|
@ -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 <typename T>
|
||||
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;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 */
|
||||
|
|
|
|||
|
|
@ -65,8 +65,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|||
# include <string> // 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue