Removing stdint.h dependency from the public API to avoid conflicts with other libraries.

Cleaned up aiTexture.h, AssimpPCH.h and MaterialSystem.h.
Updated child apps & makefiles to reflect these changes.

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

code/AssimpPCH.h

@@ -39,43 +39,66 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ---------------------------------------------------------------------------
 */
 
+/** @file AssimpPCH.h
+ *  PCH master include. Every unit in Assimp has to include it.
+ */
+
 #ifndef ASSIMP_PCH_INCLUDED
 #define ASSIMP_PCH_INCLUDED
-
 #define ASSIMP_INTERNAL_BUILD
 
-// Compile config
+// ----------------------------------------------------------------------------------------
+/* General compile config taken from aiDefines.h. It is important that the user compiles
+ * using exactly the same settings in aiDefines.h. Settings in AssimpPCH.h may differ,
+ * they won't affect the public API.
+ */
 #include "../include/aiDefines.h"
 
-// Undefine the min/max macros defined by some platform headers
+/* Include our stdint.h replacement header for MSVC, take the global header for gcc/mingw
+ */
+#ifdef _MSC_VER
+#	include "../include/Compiler/pstdint.h"
+#else
+#	include <stdint.h>
+#endif
+
+/* Undefine the min/max macros defined by some platform headers (namely Windows.h) to 
+ * avoid obvious conflicts with std::min() and std::max(). 
+ */
 #undef min
 #undef max
 
-// Concatenate two tokens after evaluating them
-#define AI_CONCAT(a,b) a ## b
+/* Concatenate two tokens after evaluating them
+ */
+#define _AI_CONCAT(a,b)  a ## b
+#define  AI_CONCAT(a,b)  _AI_CONCAT(a,b)
 
-// Helper macro that sets a pointer to NULL in debug builds
+/* Helper macro to set a pointer to NULL in debug builds
+ */
 #if (defined _DEBUG)
 #	define AI_DEBUG_INVALIDATE_PTR(x) x = NULL;
 #else
 #	define AI_DEBUG_INVALIDATE_PTR(x)
 #endif
 
-// If we have at least VC8 some C string manipulation functions
-// are mapped to their safe _s counterparts (e.g. _itoa_s).
+/* Beginning with MSVC8 some C string manipulation functions are mapped to their _safe_
+ * counterparts (e.g. _itoa_s). This avoids a lot of trouble with deprecation warnings.
+ */
 #if _MSC_VER >= 1400 && !(defined _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES)
 #	define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
 #endif
 
-// size_t to unsigned int, possible loss of data.
-// Yes, the compiler is right with his warning, but this loss of data
-// won't be a problem for us. So shut up little boy.
+/* size_t to unsigned int, possible loss of data. The compiler is right with his warning
+ * but this loss of data won't be a problem for us. So shut up, little boy.
+ */
 #ifdef _MSC_VER
 #	pragma warning (disable : 4267)
 #endif
 
-// Actually that's not required for MSVC (it is included somewhere in 
-// the STL ..) but it is necessary for build with STLport.
+// ----------------------------------------------------------------------------------------
+/* Actually that's not required for MSVC. It is included somewhere in the deeper parts of
+ * the MSVC STL but it's necessary for proper build with STLport.
+ */
 #include <ctype.h>
 
 // Runtime/STL headers
@@ -109,7 +132,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "StreamReader.h"
 #include "qnan.h"
 
-// boost headers - take them from the workaround dir if possible
+// ----------------------------------------------------------------------------------------
+/* boost headers - if -noboost is enabled, take it from the workaround directory
+ * using hardcoded paths. This has the advantage that the user doesn't need to specify
+ * 'include/BoostWorkaround' as additional include path.
+ */
+// ----------------------------------------------------------------------------------------
 #ifdef ASSIMP_BUILD_BOOST_WORKAROUND
 
 #	include "../include/BoostWorkaround/boost/scoped_ptr.hpp"

code/MaterialSystem.h

@@ -38,21 +38,25 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ----------------------------------------------------------------------
 */
 
-/** @file Definition of the base class for all importer worker classes. */
+/** @file MaterialSystem.h
+ *  Definition of the #MaterialHelper utility class.
+ */
 #ifndef AI_MATERIALSYSTEM_H_INC
 #define AI_MATERIALSYSTEM_H_INC
 
 #include "../include/aiMaterial.h"
 namespace Assimp	{
 
-
 // ----------------------------------------------------------------------------------------
-/** Internal material helper class. Intended to be used to fill an aiMaterial
-    structure easily. */
+/** Internal material helper class deriving from aiMaterial.
+ *
+ *  Intended to be used to fill an aiMaterial structure more easily.
+ */
 class ASSIMP_API MaterialHelper : public ::aiMaterial
 {
 public:
 
+	// Construction and destruction
 	MaterialHelper();
 	~MaterialHelper();
 
@@ -74,7 +78,6 @@ public:
 		unsigned int index ,
 		aiPropertyTypeInfo pType);
 
-
 	// ------------------------------------------------------------------------------
 	/** @brief Add a string property with a given key and type info to the 
 	 *  material structure 
@@ -89,7 +92,6 @@ public:
 		unsigned int type  = 0,
 		unsigned int index = 0);
 
-
 	// ------------------------------------------------------------------------------
 	/** @brief Add a property with a given key to the material structure 
 	 *  @param pInput Pointer to the input data
@@ -105,7 +107,6 @@ public:
 		unsigned int type  = 0,
 		unsigned int index = 0);
 
-
 	// ------------------------------------------------------------------------------
 	/** @brief Remove a given key from the list.
 	 *
@@ -116,15 +117,13 @@ public:
 		unsigned int type  = 0,
 		unsigned int index = 0);
 
-
 	// ------------------------------------------------------------------------------
 	/** @brief Removes all properties from the material.
 	 *
-	 *  The array remains allocated, so adding new properties is quite fast.
+	 *  The data array remains allocated so adding new properties is quite fast.
 	 */
 	void Clear();
 
-
 	// ------------------------------------------------------------------------------
 	/** Computes a hash (hopefully unique) from all material properties
 	 *  The hash value reflects the current property state, so if you add any
@@ -138,16 +137,16 @@ public:
 	 */
 	uint32_t ComputeHash(bool includeMatName = false);
 
-
 	// ------------------------------------------------------------------------------
 	/** Copy the property list of a material
-	 *  \param pcDest Destination material
-	 *  \param pcSrc Source material
+	 *  @param pcDest Destination material
+	 *  @param pcSrc Source material
 	 */
 	static void CopyPropertyList(MaterialHelper* pcDest, 
 		const MaterialHelper* pcSrc);
 
-	// For internal use
+public:
+	// For internal use. That's why it's public.
 	void _InternDestruct();
 };
 

include/aiDefines.h

@@ -41,82 +41,86 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 /** @file aiDefines.h
  *  @brief Assimp build configuration setup. See the notes in the comment
- *  blocks to find out how you can customize your Assimp build.
+ *  blocks to find out how to customize _your_ Assimp build.
  */
 
 #ifndef INCLUDED_AI_DEFINES_H
 #define INCLUDED_AI_DEFINES_H
 
 	//////////////////////////////////////////////////////////////////////////
-	// Define ASSIMP_BUILD_NO_XX_IMPORTER to disable a specific
-	// file format loader. The loader is be excluded from the
-	// build in this case. 'XX' stands for the most common file
-	// extension of the file format. E.g.: 
-    // ASSIMP_BUILD_NO_X_IMPORTER disables the X loader.
-	//
-	// Other configuration switches:
-	//    ASSIMP_BUILD_NO_COMPRESSED_X 
-	//      - Disable support for compressed X files, removes the
-	//        dependency from the zlib inflate algorithm.
-	//
+	/* Define ASSIMP_BUILD_NO_XX_IMPORTER to disable a specific
+	 * file format loader. The loader is be excluded from the
+	 * build in this case. 'XX' stands for the most common file
+	 * extension of the file format. E.g.: 
+	 * ASSIMP_BUILD_NO_X_IMPORTER disables the X loader.
+	 *
+	 * If you're unsure about that, take a look at the implementation of the
+	 * import plugin you wish to disable. You'll find the right define in the
+	 * first lines of the corresponding unit.
+	 *
+	 * Other (mixed) configuration switches are listed here:
+	 *    ASSIMP_BUILD_NO_COMPRESSED_X 
+	 *      - Disable support for compressed X files */
+	//////////////////////////////////////////////////////////////////////////
 #ifndef ASSIMP_BUILD_NO_COMPRESSED_X
 #	define ASSIMP_BUILD_NEED_Z_INFLATE
 #endif
 
 	//////////////////////////////////////////////////////////////////////////
-	// Define ASSIMP_BUILD_NO_XX_PROCESS to disable a specific
-	// post-processing step. 
-	// Full list of all 'XX':
-	// CALCTANGENTS
-	// JOINVERTICES
-	// TRIANGULATE
-	// GENFACENORMALS
-	// GENVERTEXNORMALS
-	// REMOVEVC
-	// SPLITLARGEMESHES
-	// PRETRANSFORMVERTICES
-	// LIMITBONEWEIGHTS
-	// VALIDATEDS
-	// IMPROVECACHELOCALITY
-	// FIXINFACINGNORMALS
-	// REMOVE_REDUNDANTMATERIALS
-	// OPTIMIZEGRAPH
-	// SORTBYPTYPE
-	// FINDINVALIDDATA
-	// TRANSFORMTEXCOORDS
-	// GENUVCOORDS
-	// ENTITYMESHBUILDER
-	// MAKELEFTHANDED
-	// FLIPUVS
-	// FLIPWINDINGORDER
-	// *OPTIMIZEMESHES
-	// *OPTIMIZEANIMS
-	// *OPTIMIZENODES
-	// *GENENTITYMESHES
+	/* Define ASSIMP_BUILD_NO_XX_PROCESS to disable a specific
+	 * post processing step. This is the current list of process names ('XX'):
+	 * CALCTANGENTS
+	 * JOINVERTICES
+	 * TRIANGULATE
+	 * GENFACENORMALS
+	 * GENVERTEXNORMALS
+	 * REMOVEVC
+	 * SPLITLARGEMESHES
+	 * PRETRANSFORMVERTICES
+	 * LIMITBONEWEIGHTS
+	 * VALIDATEDS
+	 * IMPROVECACHELOCALITY
+	 * FIXINFACINGNORMALS
+	 * REMOVE_REDUNDANTMATERIALS
+	 * OPTIMIZEGRAPH
+	 * SORTBYPTYPE
+	 * FINDINVALIDDATA
+	 * TRANSFORMTEXCOORDS
+	 * GENUVCOORDS
+	 * ENTITYMESHBUILDER
+	 * MAKELEFTHANDED
+	 * FLIPUVS
+	 * FLIPWINDINGORDER
+	 * OPTIMIZEMESHES
+	 * OPTIMIZEANIMS
+	 * OPTIMIZEGRAPH
+	 * GENENTITYMESHES
+	 * FIXTEXTUREPATHS */
+	//////////////////////////////////////////////////////////////////////////
 
 // Compiler specific includes and definitions
 #if (defined _MSC_VER)
 #	undef ASSIMP_API
 
-	// Include our workaround stdint.h - VC doesn't have one
-#	include "./../include/Compiler/pstdint.h"
-
 	//////////////////////////////////////////////////////////////////////////
-	// Define ASSIMP_BUILD_DLL_EXPORT to build a DLL of the library
+	/* Define 'ASSIMP_BUILD_DLL_EXPORT' to build a DLL of the library */
+	//////////////////////////////////////////////////////////////////////////
 #	if (defined ASSIMP_BUILD_DLL_EXPORT)
 #		define ASSIMP_API __declspec(dllexport)
 #		pragma warning (disable : 4251)
 
 	//////////////////////////////////////////////////////////////////////////
-	// Define ASSIMP_DLL before including Assimp to use ASSIMP in
-	// an external DLL (otherwise a static library is used)
+	/* Define 'ASSIMP_DLL' before including Assimp to link to ASSIMP in
+	 * an external DLL under Windows. Default is static linkage. */
+	//////////////////////////////////////////////////////////////////////////
 #	elif (defined ASSIMP_DLL)
 #		define ASSIMP_API __declspec(dllimport)
 #	else
 #		define ASSIMP_API 
 #	endif
 
-	// Force the compiler to inline a function, if supported
+	/* Force the compiler to inline a function, if supported
+	 */
 #	define AI_FORCE_INLINE __forceinline
 
 #else
@@ -125,15 +129,17 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #endif // (defined _MSC_VER)
 
 #ifdef __cplusplus
-	// No explicit 'struct' and 'enum' tags for C++, we don't want to 
-	// confuse the AI (:-)) of our IDE.
+	/* No explicit 'struct' and 'enum' tags for C++, we don't want to 
+	 * confuse the _AI_ of our IDE.
+	 */
 #	define C_STRUCT
 #	define C_ENUM
 #else
 	//////////////////////////////////////////////////////////////////////////
-	// To build the documentation, make sure ASSIMP_DOXYGEN_BUILD
-	// is defined by Doxygen's preprocessor. The corresponding
-	// entries in the DoxyFile look like this:
+	/* To build the documentation, make sure ASSIMP_DOXYGEN_BUILD
+	 * is defined by Doxygen's preprocessor. The corresponding
+	 * entries in the DOXYFILE are: */
+	//////////////////////////////////////////////////////////////////////////
 #if 0
 	ENABLE_PREPROCESSING   = YES
 	MACRO_EXPANSION        = YES
@@ -146,10 +152,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 	SKIP_FUNCTION_MACROS   = YES
 #endif
 	//////////////////////////////////////////////////////////////////////////
-	// Doxygen gets confused if we use c-struct typedefs to avoid
-	// the explicit 'struct' notation. This trick here has the same
-	// effect as the TYPEDEF_HIDES_STRUCT option, but we don't need
-	// to typedef all structs/enums.
+	/* Doxygen gets confused if we use c-struct typedefs to avoid
+	 * the explicit 'struct' notation. This trick here has the same
+	 * effect as the TYPEDEF_HIDES_STRUCT option, but we don't need
+	 * to typedef all structs/enums. */
+	 //////////////////////////////////////////////////////////////////////////
 #	if (defined ASSIMP_DOXYGEN_BUILD)
 #		define C_STRUCT 
 #		define C_ENUM   
@@ -167,10 +174,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 #endif
 	//////////////////////////////////////////////////////////////////////////
-	// Define ASSIMP_BUILD_BOOST_WORKAROUND to compile assimp
-	// without boost. This is done by using a few workaround
-	// classes. However, some assimp features are not available
-	// in this case. This implies the ASSIMP_BUILD_SINGLETHREADED option.
+	/* Define 'ASSIMP_BUILD_BOOST_WORKAROUND' to compile assimp
+	 * without boost. This is done by using a few workaround
+	 * classes and brings some limitations (e.g. some logging won't be done,
+	 * the library won't utilize threads or be threadsafe at all). 
+	 * This implies the 'ASSIMP_BUILD_SINGLETHREADED' setting. */
+	 //////////////////////////////////////////////////////////////////////////
 #ifdef ASSIMP_BUILD_BOOST_WORKAROUND
 
 	// threading support requires boost
@@ -178,15 +187,14 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #	define ASSIMP_BUILD_SINGLETHREADED
 #endif
 
-#endif
+#endif // !! ASSIMP_BUILD_BOOST_WORKAROUND
 
 	//////////////////////////////////////////////////////////////////////////
-	// Define ASSIMP_BUILD_SINGLETHREADED to compile assimp
-	// without threading support. The library doesn't utilize
-	// threads then, and is itself not threadsafe.
-	// If this flag is specified, boost::threads is *not* required.
-
-	// TODO
+	/* Define ASSIMP_BUILD_SINGLETHREADED to compile assimp
+	 * without threading support. The library doesn't utilize
+	 * threads then and is itself not threadsafe.
+	 * If this flag is specified boost::threads is *not* required. */
+	//////////////////////////////////////////////////////////////////////////
 #ifndef ASSIMP_BUILD_SINGLETHREADED
 #	define ASSIMP_BUILD_SINGLETHREADED
 #endif
@@ -200,17 +208,14 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #	define ASSIMP_BUILD_DEBUG
 #endif
 
-// Make sure NULL is defined
-#ifndef NULL
-#	define NULL 0
-#endif
-
-// Use our own definition of PI here
+/* This is PI. Hi PI.
+ */
 #define AI_MATH_PI		(3.1415926538)
 #define AI_MATH_TWO_PI	(AI_MATH_PI * 2.0)
 #define AI_MATH_HALF_PI	(AI_MATH_PI * 0.5)
 
-// Tiny macro to convert from radians to degrees and the reverse
+/* Tiny macro to convert from radians to degrees and the opposite
+ */
 #define AI_DEG_TO_RAD(x) (x*0.0174532925f)
 #define AI_RAD_TO_DEG(x) (x*57.2957795f)
 

include/aiTexture.h

@@ -109,14 +109,14 @@ struct aiTexel
 
 // --------------------------------------------------------------------------------
 /** Helper structure to describe an embedded texture
-* 
-* Normally textures are contained in external files but some file formats
-* embed them directly in the model file. There are two types of embedded
-* textures: 1. Uncompressed textures. The color data is directly given.
-* 2. Compressed textures stored in a file format like png or jpg. The raw
-* file is given, the application must utilize an image decoder (e.g. DevIL)
-* to get access to the color data.
-*/
+ * 
+ * Normally textures are contained in external files but some file formats embed
+ * them directly in the model file. There are two types of embedded textures: 
+ * 1. Uncompressed textures. The color data is given in an uncompressed format. 
+ * 2. Compressed textures stored in a file format like png or jpg. The raw file 
+ * bytes are given so the application must utilize an image decoder (e.g. DevIL) to
+ * get access to the actual color data.
+ */
 struct aiTexture
 {
 	/** Width of the texture, in pixels

tools/assimp_cmd/Main.h

@@ -58,6 +58,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include <assimp.hpp>
 #include <DefaultLogger.h>
 
+#include <../code/AssimpPCH.h> /* to get stdint.h */
 #include <../code/fast_atof.h>
 #include <../code/StringComparison.h>
 #include <../code/Hash.h>

tools/assimp_cmd/makefile.mingw

@@ -27,7 +27,7 @@ INCLUDEFLAGS = -I../../include
 LIBRARYFLAGS = -L../../bin/mingw/
 
 # Preprocessor defines for gcc
-DEFINEFLAGS =  
+DEFINEFLAGS =  -DASSIMP_BUILD_BOOST_WORKAROUND
 
 # GCC compiler flags 
 CPPFLAGS=-Wall

tools/assimp_view/assimp_view.h

@@ -58,6 +58,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "assimp.hpp"
 #include "LogStream.h"
 #include "DefaultLogger.h"
+
+#include "../../code/AssimpPCH.h" /* HACK */
  
 #include "MaterialSystem.h"   // MaterialHelper clas
 #include "StringComparison.h" // ASSIMP_stricmp and ASSIMP_strincmp

workspaces/vc9/assimp.vcproj

@@ -1927,10 +1927,6 @@
 			<Filter
 				Name="process"
 				>
-				<File
-					RelativePath="..\..\code\AssimpPCH.h"
-					>
-				</File>
 				<File
 					RelativePath="..\..\code\CalcTangentsProcess.cpp"
 					>
@@ -2035,6 +2031,10 @@
 					RelativePath="..\..\code\PretransformVertices.h"
 					>
 				</File>
+				<File
+					RelativePath="..\..\code\ProcessHelper.h"
+					>
+				</File>
 				<File
 					RelativePath="..\..\code\RemoveRedundantMaterials.cpp"
 					>
@@ -2091,14 +2091,6 @@
 					RelativePath="..\..\code\ValidateDataStructure.h"
 					>
 				</File>
-				<Filter
-					Name="util"
-					>
-					<File
-						RelativePath="..\..\code\ProcessHelper.h"
-						>
-					</File>
-				</Filter>
 			</Filter>
 			<Filter
 				Name="pch"
@@ -2203,6 +2195,10 @@
 						/>
 					</FileConfiguration>
 				</File>
+				<File
+					RelativePath="..\..\code\AssimpPCH.h"
+					>
+				</File>
 			</Filter>
 			<Filter
 				Name="logging"