- add metadata support to aiScene. Some doc cleanup. Add const versions of aiScene::aiNode.

include/assimp/metadata.h

@@ -0,0 +1,120 @@
+/*
+---------------------------------------------------------------------------
+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 metadata.h
+ *  @brief Defines the data structures for holding node meta information.
+ */
+#ifndef __AI_METADATA_H_INC__
+#define __AI_METADATA_H_INC__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// -------------------------------------------------------------------------------
+/**
+  * Container for holding metadata.
+  *
+  * Metadata is a key-value store using string keys and values.
+  */
+ // -------------------------------------------------------------------------------
+struct aiMetadata 
+{
+	/** Length of the mKeys and mValues arrays, respectively */
+	unsigned int mNumProperties;
+
+	/** Arrays of keys, may not be NULL. Entries in this array may not be NULL as well. */
+	C_STRUCT aiString** mKeys;
+
+	/** Arrays of values, may not be NULL. Entries in this array may be NULL if the
+	  * corresponding property key has no assigned value. */
+	C_STRUCT aiString** mValues;
+
+#ifdef __cplusplus
+
+	/** Constructor */
+	aiMetadata()
+	{
+		// set all members to zero by default
+		mKeys = NULL;
+		mValues = NULL;
+		mNumProperties = 0;
+	}
+
+
+	/** Destructor */
+	~aiMetadata()
+	{
+		if (mKeys && mValues) {
+			for (unsigned i=0; i<mNumProperties; ++i) {
+				if (mKeys[i]) {
+					delete mKeys[i];
+				}
+				if (mValues[i]) {
+					delete mValues[i];
+				}
+			}
+			delete [] mKeys;
+			delete [] mValues;
+		}
+	}
+
+
+	inline bool Get(const aiString& key, aiString& value)
+	{
+		for (unsigned i=0; i<mNumProperties; ++i) {
+			if (mKeys[i] && *mKeys[i]==key) {
+				value=*mValues[i];
+				return true;
+			}
+		}
+		return false;
+	}
+#endif // __cplusplus
+};
+
+#ifdef __cplusplus
+} //extern "C" {
+#endif
+
+#endif // __AI_METADATA_H_INC__
+
+

include/assimp/scene.h

@@ -52,11 +52,13 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "camera.h"
 #include "material.h"
 #include "anim.h"
+#include "metadata.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+
 // -------------------------------------------------------------------------------
 /** A node in the imported hierarchy. 
  *
@@ -71,16 +73,24 @@ struct aiNode
 	/** The name of the node. 
 	 *
 	 * The name might be empty (length of zero) but all nodes which 
-	 * need to be accessed afterwards by bones or anims are usually named.
+	 * need to be referenced by either bones or animations are named.
-	 * Multiple nodes may have the same name, but nodes which are accessed
+	 * Multiple nodes may have the same name, except for nodes which are referenced
-	 * by bones (see #aiBone and #aiMesh::mBones) *must* be unique.
+	 * by bones (see #aiBone and #aiMesh::mBones). Their names *must* be unique.
 	 * 
-	 * Cameras and lights are assigned to a specific node name - if there
+	 * Cameras and lights reference a specific node by name - if there
-	 * are multiple nodes with this name, they're assigned to each of them.
+	 * are multiple nodes with this name, they are assigned to each of them.
 	 * <br>
-	 * There are no limitations regarding the characters contained in
+	 * There are no limitations with regard to the characters contained in
-	 * this text. You should be able to handle stuff like whitespace, tabs,
+	 * the name string as it is usually taken directly from the source file. 
-	 * linefeeds, quotation marks, ampersands, ... .
+	 * 
+	 * Implementations should be able to handle tokens such as whitespace, tabs,
+	 * line feeds, quotation marks, ampersands etc.
+	 *
+	 * Sometimes assimp introduces new nodes not present in the source file
+	 * into the hierarchy (usually out of necessity because sometimes the
+	 * source hierarchy format is simply not compatible). Their names are
+	 * surrounded by @verbatim <> @endverbatim e.g.
+	 *  @verbatim<DummyRootNode> @endverbatim.
 	 */
 	C_STRUCT aiString mName;
 
@@ -102,24 +112,39 @@ struct aiNode
 	/** The meshes of this node. Each entry is an index into the mesh */
 	unsigned int* mMeshes;
 
+	/** Metadata associated with this node or NULL if there is no metadata.
+	  *  Whether any metadata is generated depends on the source file format. See the
+	  * @link importer_notes @endlink page for more information on every source file
+	  * format. Importers that don't document any metadata don't write any. 
+	  */
+	C_STRUCT aiMetadata* mMetaData;
+
 #ifdef __cplusplus
 	/** Constructor */
 	aiNode() 
-	{ 
 		// set all members to zero by default
-		mParent = NULL; 
+		: mName()
-		mNumChildren = 0; mChildren = NULL;
+		, mParent()
-		mNumMeshes = 0; mMeshes = NULL;
+		, mNumChildren()
+		, mChildren()
+		, mNumMeshes()
+		, mMeshes()
+		, mMetaData()
+	{
 	}
+	
 
 	/** Construction from a specific name */
 	aiNode(const std::string& name) 
-	{ 
 		// set all members to zero by default
-		mParent = NULL; 
+		: mName(name)
-		mNumChildren = 0; mChildren = NULL;
+		, mParent()
-		mNumMeshes = 0; mMeshes = NULL;
+		, mNumChildren()
-		mName = name;
+		, mChildren()
+		, mNumMeshes()
+		, mMeshes()
+		, mMetaData()
+	{
 	}
 
 	/** Destructor */
@@ -134,8 +159,10 @@ struct aiNode
 		}
 		delete [] mChildren;
 		delete [] mMeshes;
+		delete mMetaData;
 	}
 
+
 	/** Searches for a node with a specific name, beginning at this
 	 *  nodes. Normally you will call this method on the root node
 	 *  of the scene.
@@ -143,22 +170,45 @@ struct aiNode
 	 *  @param name Name to search for
 	 *  @return NULL or a valid Node if the search was successful.
 	 */
+	inline const aiNode* FindNode(const aiString& name) const
+	{
+		return FindNode(name.data);
+	}
+
+
 	inline aiNode* FindNode(const aiString& name)
 	{
 		return FindNode(name.data);
 	}
 
+
 	/** @override
 	 */
-	inline aiNode* FindNode(const char* name)
+	inline const aiNode* FindNode(const char* name) const
 	{
 		if (!::strcmp( mName.data,name))return this;
 		for (unsigned int i = 0; i < mNumChildren;++i)
 		{
-			aiNode* p = mChildren[i]->FindNode(name);
+			const aiNode* const p = mChildren[i]->FindNode(name);
-			if (p)return p;
+			if (p) {
+				return p;
+			}
 		}
-		// there is definitely no sub node with this name
+		// there is definitely no sub-node with this name
+		return NULL;
+	}
+
+	inline aiNode* FindNode(const char* name) 
+	{
+		if (!::strcmp( mName.data,name))return this;
+		for (unsigned int i = 0; i < mNumChildren;++i)
+		{
+			aiNode* const p = mChildren[i]->FindNode(name);
+			if (p) {
+				return p;
+			}
+		}
+		// there is definitely no sub-node with this name
 		return NULL;
 	}