+ add aiImporterDesc API to hold importer meta information.

- cleanup some Importer APIs: FindLoader -> GetImporter, add some utility APIs. Note that this is a breaking API change.

git-svn-id: https://assimp.svn.sourceforge.net/svnroot/assimp/trunk@1232 67173fc5-114c-0410-ac8e-9d2fd5bffc1f

code/AssimpPCH.h

@@ -136,6 +136,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "../include/assimp/IOStream.hpp"
 #include "../include/assimp/IOSystem.hpp"
 #include "../include/assimp/scene.h"
+#include "../include/assimp/importerdesc.h"
 #include "../include/assimp/postprocess.h"
 #include "../include/assimp/Importer.hpp"
 #include "../include/assimp/Exporter.hpp"

code/BaseImporter.h

@@ -190,7 +190,15 @@ public:
 protected:
 
 	// -------------------------------------------------------------------
-	/** Called by Importer::GetExtensionList() for each loaded importer.
+	/** Called by #Importer::GetImporterInfo to get a description of 
+	 *  some loader features. Importer need not provide this structure,
+	 *  but it is highly recommended. */
+	virtual const aiImporterDesc* GetInfo() {
+		return NULL;
+	}
+
+	// -------------------------------------------------------------------
+	/** Called by #Importer::GetExtensionList for each loaded importer.
 	 *  Implementations are expected to insert() all file extensions
 	 *  handled by them into the extension set. A loader capable of
 	 *  reading certain files with the extension BLA would place the

code/BlenderLoader.cpp

@@ -71,12 +71,12 @@ using namespace Assimp;
 using namespace Assimp::Blender;
 using namespace Assimp::Formatter;
 
-static const aiLoaderDesc blenderDesc = {
+static const aiImporterDesc blenderDesc = {
 	"Blender 3D Importer \nhttp://www.blender3d.org",
-	"Assimp Team",
 	"",
 	"",
-	aiLoaderFlags_SupportBinaryFlavour | aiLoaderFlags_Experimental,
+	"",
+	aiImporterFlags_SupportBinaryFlavour | aiImporterFlags_Experimental,
 	0,
 	0,
 	2,
@@ -123,9 +123,9 @@ void BlenderImporter::GetExtensionList(std::set<std::string>& app)
 
 // ------------------------------------------------------------------------------------------------
 // Loader registry entry
-const aiLoaderDesc& BlenderImporter::GetInfo () const
+const aiImporterDesc* BlenderImporter::GetInfo () const
 {
-	return blenderDesc;
+	return &blenderDesc;
 }
 
 // ------------------------------------------------------------------------------------------------

code/BlenderLoader.h

@@ -85,32 +85,6 @@ namespace Assimp	{
 		class BlenderModifier;
 	}
 
-enum aiLoaderFlags 
-{
-	aiLoaderFlags_SupportAsciiFlavour = 0x1,
-	aiLoaderFlags_SupportBinaryFlavour = 0x2,
-	aiLoaderFlags_SupportCompressedFlavour = 0x4,
-
-	aiLoaderFlags_LimitedSupport = 0x8,
-
-	aiLoaderFlags_Experimental = 0x10,
-	aiLoaderFlags_Testing = 0x20,
-	aiLoaderFlags_Production = 0x40
-};
-
-struct aiLoaderDesc 
-{
-	const char* mName;
-	const char* mAuthor;
-	const char* mMaintainer;
-	const char* mComments;
-	unsigned int mFlags;
-
-	unsigned int mMinMajor;
-	unsigned int mMinMinor;
-	unsigned int mMaxMajor;
-	unsigned int mMaxMinor;
-};
 
 
 // -------------------------------------------------------------------------------------------
@@ -136,7 +110,7 @@ public:
 protected:
 
 	// --------------------
-	const aiLoaderDesc& GetInfo () const;
+	const aiImporterDesc* GetInfo () const;
 
 	// --------------------
 	void GetExtensionList(std::set<std::string>& app);

code/CMakeLists.txt

@@ -46,6 +46,7 @@ SET( PUBLIC_HEADERS
 	${HEADER_PATH}/vector3.inl
 	${HEADER_PATH}/version.h
 	${HEADER_PATH}/cimport.h
+	${HEADER_PATH}/importerdesc.h
 	${HEADER_PATH}/Importer.hpp
 	${HEADER_PATH}/DefaultLogger.hpp
 	${HEADER_PATH}/ProgressHandler.hpp

code/Importer.cpp

@@ -818,12 +818,44 @@ const aiScene* Importer::ApplyPostProcessing(unsigned int pFlags)
 // Helper function to check whether an extension is supported by ASSIMP
 bool Importer::IsExtensionSupported(const char* szExtension) const
 {
-	return NULL != FindLoader(szExtension);
+	return NULL != GetImporter(szExtension);
+}
+
+// ------------------------------------------------------------------------------------------------
+size_t Importer::GetImporterCount() const
+{
+	return pimpl->mImporter.size();
+}
+
+// ------------------------------------------------------------------------------------------------
+const aiImporterDesc* Importer::GetImporterInfo(size_t index) const
+{
+	if (index >= pimpl->mImporter.size()) {
+		return NULL;
+	}
+	return pimpl->mImporter[index]->GetInfo();
+}
+
+
+// ------------------------------------------------------------------------------------------------
+BaseImporter* Importer::GetImporter (size_t index) const
+{
+	if (index >= pimpl->mImporter.size()) {
+		return NULL;
+	}
+	return pimpl->mImporter[index];
+}
+
+// ------------------------------------------------------------------------------------------------
+// Find a loader plugin for a given file extension
+BaseImporter* Importer::GetImporter (const char* szExtension) const
+{
+	return GetImporter(GetImporterIndex(szExtension));
 }
 
 // ------------------------------------------------------------------------------------------------
 // Find a loader plugin for a given file extension
-BaseImporter* Importer::FindLoader (const char* szExtension) const
+size_t Importer::GetImporterIndex (const char* szExtension) const
 {
 	ai_assert(szExtension);
 	ASSIMP_BEGIN_EXCEPTION_REGION();
@@ -844,12 +876,12 @@ BaseImporter* Importer::FindLoader (const char* szExtension) const
 		(*i)->GetExtensionList(str);
 		for (std::set<std::string>::const_iterator it = str.begin(); it != str.end(); ++it) {
 			if (ext == *it) {
-				return (*i);
+				return std::distance(static_cast< std::vector<BaseImporter*>::const_iterator >(pimpl->mImporter.begin()), i);
 			}
 		}
 	}
-	ASSIMP_END_EXCEPTION_REGION(BaseImporter*);
-	return NULL;
+	ASSIMP_END_EXCEPTION_REGION(size_t);
+	return static_cast<size_t>(-1);
 }
 
 // ------------------------------------------------------------------------------------------------

include/assimp/Importer.hpp

@@ -84,6 +84,9 @@ namespace Assimp	{
 
 struct aiScene;
 
+// importerdesc.h
+struct aiImporterDesc;
+
 /** @namespace Assimp Assimp's CPP-API and all internal APIs */
 namespace Assimp	{
 
@@ -468,6 +471,35 @@ public:
 	 * following methods is called: #ReadFile(), #FreeScene(). */
 	const char* GetErrorString() const;
 
+	// -------------------------------------------------------------------
+	/** Returns the scene loaded by the last successful call to ReadFile()
+	 *
+	 * @return Current scene or NULL if there is currently no scene loaded */
+	const aiScene* GetScene() const;
+
+	// -------------------------------------------------------------------
+	/** Returns the scene loaded by the last successful call to ReadFile()
+	 *  and releases the scene from the ownership of the Importer 
+	 *  instance. The application is now responsible for deleting the
+	 *  scene. Any further calls to GetScene() or GetOrphanedScene()
+	 *  will return NULL - until a new scene has been loaded via ReadFile().
+	 *
+	 * @return Current scene or NULL if there is currently no scene loaded
+	 * @note Use this method with maximal caution, and only if you have to.
+	 *   By design, aiScene's are exclusively maintained, allocated and
+	 *   deallocated by Assimp and no one else. The reasoning behind this
+	 *   is the golden rule that deallocations should always be done
+	 *   by the module that did the original allocation because heaps
+	 *   are not necessarily shared. GetOrphanedScene() enforces you
+	 *   to delete the returned scene by yourself, but this will only
+	 *   be fine if and only if you're using the same heap as assimp.
+	 *   On Windows, it's typically fine provided everything is linked
+	 *   against the multithreaded-dll version of the runtime library.
+	 *   It will work as well for static linkage with Assimp.*/
+	aiScene* GetOrphanedScene();
+
+
+
 
 	// -------------------------------------------------------------------
 	/** Returns whether a given file extension is supported by ASSIMP.
@@ -486,7 +518,6 @@ public:
 	 * @see IsExtensionSupported(const char*) */
 	inline bool IsExtensionSupported(const std::string& szExtension) const;
 
-
 	// -------------------------------------------------------------------
 	/** Get a full list of all file extensions supported by ASSIMP.
 	 *
@@ -507,46 +538,52 @@ public:
 	 * @see GetExtensionList(aiString&)*/
 	inline void GetExtensionList(std::string& szOut) const;
 
+	// -------------------------------------------------------------------
+	/** Get the number of importrs currently registered with Assimp. */
+	size_t GetImporterCount() const;
+
+	// -------------------------------------------------------------------
+	/** Get meta data for the importer corresponding to a specific index..
+	*
+	*  For the declaration of #aiImporterDesc, include <assimp/importerdesc.h>.
+	*  @param index Index to query, must be within [0,GetImporterCount())
+	*  @return Importer meta data structure, NULL if the index does not
+	*     exist or if the importer doesn't offer meta information (
+	*     importers may do this at the cost of being hated by their peers).*/
+	const aiImporterDesc* GetImporterInfo(size_t index) const;
 
 	// -------------------------------------------------------------------
-	/** Find the loader corresponding to a specific file extension.
+	/** Find the importer corresponding to a specific index.
 	*
-	*  This is quite similar to IsExtensionSupported() except a
+	*  @param index Index to query, must be within [0,GetImporterCount())
+	*  @return Importer instance. NULL if the index does not
+	*     exist. */
+	BaseImporter* GetImporter(size_t index) const;
+
+	// -------------------------------------------------------------------
+	/** Find the importer corresponding to a specific file extension.
+	*
+	*  This is quite similar to #IsExtensionSupported except a
 	*  BaseImporter instance is returned.
 	*  @param szExtension Extension to check for. The following formats
-	*    are recgnized (BAH being the file extension): "BAH" (comparison
+	*    are recognized (BAH being the file extension): "BAH" (comparison
 	*    is case-insensitive), ".bah", "*.bah" (wild card and dot
 	*    characters at the beginning of the extension are skipped).
-	*  @return NULL if there is no loader for the extension.*/
-	BaseImporter* FindLoader (const char* szExtension) const;
-
+	*  @return NULL if no importer is found*/
+	BaseImporter* GetImporter (const char* szExtension) const;
 
 	// -------------------------------------------------------------------
-	/** Returns the scene loaded by the last successful call to ReadFile()
-	 *
-	 * @return Current scene or NULL if there is currently no scene loaded */
-	const aiScene* GetScene() const;
+	/** Find the importer index corresponding to a specific file extension.
+	*
+	*  @param szExtension Extension to check for. The following formats
+	*    are recognized (BAH being the file extension): "BAH" (comparison
+	*    is case-insensitive), ".bah", "*.bah" (wild card and dot
+	*    characters at the beginning of the extension are skipped).
+	*  @return (size_t)-1 if no importer is found */
+	size_t GetImporterIndex (const char* szExtension) const;
+
+
 
-	// -------------------------------------------------------------------
-	/** Returns the scene loaded by the last successful call to ReadFile()
-	 *  and releases the scene from the ownership of the Importer 
-	 *  instance. The application is now responsible for deleting the
-	 *  scene. Any further calls to GetScene() or GetOrphanedScene()
-	 *  will return NULL - until a new scene has been loaded via ReadFile().
-	 *
-	 * @return Current scene or NULL if there is currently no scene loaded
-	 * @note Use this method with maximal caution, and only if you have to.
-	 *   By design, aiScene's are exclusively maintained, allocated and
-	 *   deallocated by Assimp and no one else. The reasoning behind this
-	 *   is the golden rule that deallocations should always be done
-	 *   by the module that did the original allocation because heaps
-	 *   are not necessarily shared. GetOrphanedScene() enforces you
-	 *   to delete the returned scene by yourself, but this will only
-	 *   be fine if and only if you're using the same heap as assimp.
-	 *   On Windows, it's typically fine when everything is linked
-	 *   against the multithreaded-dll version of the runtime library.
-	 *   It will work as well for static linkage with Assimp.*/
-	aiScene* GetOrphanedScene();
 
 	// -------------------------------------------------------------------
 	/** Returns the storage allocated by ASSIMP to hold the scene data

include/assimp/importerdesc.h

@@ -0,0 +1,122 @@
+/*
+---------------------------------------------------------------------------
+Open Asset Import Library (assimp)
+---------------------------------------------------------------------------
+
+Copyright (c) 2006-2012, assimp team
+
+All rights reserved.
+
+Redistribution and use of this software in source and binary forms, 
+with or without modification, are permitted provided that the following 
+conditions are met:
+
+* Redistributions of source code must retain the above
+  copyright notice, this list of conditions and the
+  following disclaimer.
+
+* Redistributions in binary form must reproduce the above
+  copyright notice, this list of conditions and the
+  following disclaimer in the documentation and/or other
+  materials provided with the distribution.
+
+* Neither the name of the assimp team, nor the names of its
+  contributors may be used to endorse or promote products
+  derived from this software without specific prior
+  written permission of the assimp team.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+---------------------------------------------------------------------------
+*/
+
+/** @file importerdesc.h
+ *  @brief #aiImporterFlags, aiImporterDesc implementation.
+ */
+#ifndef INCLUDED_AI_IMPORTER_DESC_H
+#define INCLUDED_AI_IMPORTER_DESC_H
+
+
+/** Mixed set of flags for #aiImporterDesc, indicating some features
+  *  common to many importers*/
+enum aiImporterFlags 
+{
+	/** Indicates that there is a textual encoding of the
+	 *  file format; and that it is supported.*/
+	aiImporterFlags_SupportTextFlavour = 0x1,
+
+	/** Indicates that there is a binary encoding of the
+	 *  file format; and that it is supported.*/
+	aiImporterFlags_SupportBinaryFlavour = 0x2,
+
+	/** Indicates that there is a compressed encoding of the
+	 *  file format; and that it is supported.*/
+	aiImporterFlags_SupportCompressedFlavour = 0x4,
+
+	/** Indicates that the importer reads only a very particular
+	  * subset of the file format. This happens commonly for
+	  * declarative or procedural formats which cannot easily
+	  * be mapped to #aiScene */
+	aiImporterFlags_LimitedSupport = 0x8,
+
+	/** Indicates that the importer is highly experimental and
+	  * should be used with care. This only happens for trunk
+	  * (i.e. SVN) versions, experimental code is not included
+	  * in releases. */
+	aiImporterFlags_Experimental = 0x10,
+};
+
+
+/** Meta information about a particular importer. Importers need to fill
+ *  this structure, but they can freely decide how talkative they are. 
+ *  A common use case for loader meta info is a user interface
+ *  in which the user can choose between various import/export file
+ *  formats. Building such an UI by hand means a lot of maintenance
+ *  as importers/exporters are added to Assimp, so it might be useful
+ *  to have a common mechanism to query some rough importer
+ *  characteristics. */
+struct aiImporterDesc 
+{
+	/** Full name of the importer (i.e. Blender3D importer)*/
+	const char* mName;
+
+	/** Original author (left blank if unknown or whole assimp team) */
+	const char* mAuthor;
+
+	/** Current maintainer, left blank if the author maintains */
+	const char* mMaintainer;
+
+	/** Implementation comments, i.e. unimplemented features*/
+	const char* mComments;
+
+	/** Any combination of the #aiLoaderFlags enumerated values.
+	    These flags indicate some characteristics common to many
+		importers. */
+	unsigned int mFlags;
+
+	/** Minimum format version that can be loaded im major.minor format,
+	    both are set to 0 if there is either no version scheme 
+		or if the loader doesn't care. */
+	unsigned int mMinMajor;
+	unsigned int mMinMinor;
+
+	/** Maximum format version that can be loaded im major.minor format,
+	    both are set to 0 if there is either no version scheme 
+		or if the loader doesn't care. Loaders that expect to be
+		forward-compatible to potential future format versions should 
+		indicate  zero, otherwise they should specify the current
+		maximum version.*/
+	unsigned int mMaxMajor;
+	unsigned int mMaxMinor;
+};
+
+#endif