+ 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::FindLoader (const char* szExtension) const
+BaseImporter* Importer::GetImporter (const char* szExtension) const
+{
+	return GetImporter(GetImporterIndex(szExtension));
+}
+
+// ------------------------------------------------------------------------------------------------
+// Find a loader plugin for a given file extension
+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*);
+	ASSIMP_END_EXCEPTION_REGION(size_t);
-	return NULL;
+	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,59 +471,6 @@ public:
 	 * following methods is called: #ReadFile(), #FreeScene(). */
 	const char* GetErrorString() const;
 
-
-	// -------------------------------------------------------------------
-	/** Returns whether a given file extension is supported by ASSIMP.
-	 *
-	 * @param szExtension Extension to be checked.
-	 *   Must include a trailing dot '.'. Example: ".3ds", ".md3".
-	 *   Cases-insensitive.
-	 * @return true if the extension is supported, false otherwise */
-	bool IsExtensionSupported(const char* szExtension) const;
-
-	// -------------------------------------------------------------------
-	/** @brief Returns whether a given file extension is supported by ASSIMP.
-	 *
-	 * This function is provided for backward compatibility.
-	 * See the const char* version for detailed and up-to-date docs.
-	 * @see IsExtensionSupported(const char*) */
-	inline bool IsExtensionSupported(const std::string& szExtension) const;
-
-
-	// -------------------------------------------------------------------
-	/** Get a full list of all file extensions supported by ASSIMP.
-	 *
-	 * If a file extension is contained in the list this does of course not
-	 * mean that ASSIMP is able to load all files with this extension ---
-     * it simply means there is an importer loaded which claims to handle
-	 * files with this file extension.
-	 * @param szOut String to receive the extension list. 
-	 *   Format of the list: "*.3ds;*.obj;*.dae". This is useful for
-	 *   use with the WinAPI call GetOpenFileName(Ex). */
-	void GetExtensionList(aiString& szOut) const;
-
-	// -------------------------------------------------------------------
-	/** @brief Get a full list of all file extensions supported by ASSIMP.
-	 *
-	 * This function is provided for backward compatibility.
-	 * See the aiString version for detailed and up-to-date docs.
-	 * @see GetExtensionList(aiString&)*/
-	inline void GetExtensionList(std::string& szOut) const;
-
-
-	// -------------------------------------------------------------------
-	/** Find the loader 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
-	*    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;
-
-
 	// -------------------------------------------------------------------
 	/** Returns the scene loaded by the last successful call to ReadFile()
 	 *
@@ -543,11 +493,98 @@ public:
 	 *   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
+	 *   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.
+	 *
+	 * @param szExtension Extension to be checked.
+	 *   Must include a trailing dot '.'. Example: ".3ds", ".md3".
+	 *   Cases-insensitive.
+	 * @return true if the extension is supported, false otherwise */
+	bool IsExtensionSupported(const char* szExtension) const;
+
+	// -------------------------------------------------------------------
+	/** @brief Returns whether a given file extension is supported by ASSIMP.
+	 *
+	 * This function is provided for backward compatibility.
+	 * See the const char* version for detailed and up-to-date docs.
+	 * @see IsExtensionSupported(const char*) */
+	inline bool IsExtensionSupported(const std::string& szExtension) const;
+
+	// -------------------------------------------------------------------
+	/** Get a full list of all file extensions supported by ASSIMP.
+	 *
+	 * If a file extension is contained in the list this does of course not
+	 * mean that ASSIMP is able to load all files with this extension ---
+     * it simply means there is an importer loaded which claims to handle
+	 * files with this file extension.
+	 * @param szOut String to receive the extension list. 
+	 *   Format of the list: "*.3ds;*.obj;*.dae". This is useful for
+	 *   use with the WinAPI call GetOpenFileName(Ex). */
+	void GetExtensionList(aiString& szOut) const;
+
+	// -------------------------------------------------------------------
+	/** @brief Get a full list of all file extensions supported by ASSIMP.
+	 *
+	 * This function is provided for backward compatibility.
+	 * See the aiString version for detailed and up-to-date docs.
+	 * @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 importer corresponding to a specific index.
+	*
+	*  @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 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 no importer is found*/
+	BaseImporter* GetImporter (const char* szExtension) 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 storage allocated by ASSIMP to hold the scene data
 	 * in memory.

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