Improve documentation for new texture-loader interface and mention that the...

Improve documentation for new texture-loader interface and mention that the old solutions are deprecated.


git-svn-id: svn://svn.code.sf.net/p/irrlicht/code/trunk@4707 dfc29bdd-3216-0410-991c-e03cc46cb475

changes.txt

 --------------------------
 Changes in 1.9 (not yet released)
 
+- Add ITexture::getSource which can be used to check where the last IVideoDriver::getTexture call found the texture.
 - Add IMeshTextureLoader interface and replace texture-loading algorithms in most meshloaders.
 - CGUICheckBox no longer gives up focus on EMIE_LMOUSE_LEFT_UP (thx @Demre for reporting)
 - Bugfix: IGUIElement::addChild now prevents setting an element as it's own child.

include/IMeshLoader.h

@@ -53,7 +53,10 @@ public:
 	virtual IAnimatedMesh* createMesh(io::IReadFile* file) = 0;
 
 	//! Set a new texture loader which this meshloader can use when searching for textures.
-	/** \param textureLoader The textureloader to use. When set to NULL the mesh will not load any textures.
+	/** NOTE: Not all meshloaders do support this interface. Meshloaders which
+	support it will return a non-null value in getMeshTextureLoader from the start. Setting a
+	texture-loader to a meshloader which doesn't support it won't help.
+	\param textureLoader The textureloader to use. When set to NULL the mesh will not load any textures.
 	*/
 	virtual void setMeshTextureLoader(IMeshTextureLoader* textureLoader)
 	{
@@ -68,6 +71,8 @@ public:
 	}
 
 	//! Get the texture loader used when this meshloder searches for textures.
+	/** NOTE: not all meshloaders support this interface so this can return NULL.
+	*/
 	virtual IMeshTextureLoader* getMeshTextureLoader() const
 	{
 		return TextureLoader;

include/ISceneManager.h

@@ -187,12 +187,7 @@ namespace scene
 		 *      architecture and calculating lighting. Irrlicht can
 		 *      directly import .csm files thanks to the IrrCSM library
 		 *      created by Saurav Mohapatra which is now integrated
-		 *      directly in Irrlicht. If you are using this loader,
-		 *      please note that you'll have to set the path of the
-		 *      textures before loading .csm files. You can do this
-		 *      using
-		 *      SceneManager->getParameters()->setAttribute(scene::CSM_TEXTURE_PATH,
-		 *      &quot;path/to/your/textures&quot;);</TD>
+		 *      directly in Irrlicht.
 		 *  </TR>
 		 *  <TR>
 		 *    <TD>COLLADA (.dae, .xml)</TD>
@@ -232,9 +227,8 @@ namespace scene
 		 *        game-development. With this loader, it is possible to
 		 *        directly load all geometry is as well as textures and
 		 *        lightmaps from .dmf files. To set texture and
-		 *        material paths, see scene::DMF_USE_MATERIALS_DIRS and
-		 *        scene::DMF_TEXTURE_PATH. It is also possible to flip
-		 *        the alpha texture by setting
+		 *        material paths, see scene::DMF_USE_MATERIALS_DIRS.
+		 *        It is also possible to flip the alpha texture by setting
 		 *        scene::DMF_FLIP_ALPHA_TEXTURES to true and to set the
 		 *        material transparent reference value by setting
 		 *        scene::DMF_ALPHA_CHANNEL_REF to a float between 0 and
@@ -297,12 +291,7 @@ namespace scene
 		 *        3D packages. With this built-in importer, Irrlicht
 		 *        can read and display those files directly. This
 		 *        loader was written by Zhuck Dimitry who also created
-		 *        the whole My3DTools package. If you are using this
-		 *        loader, please note that you can set the path of the
-		 *        textures before loading .my3d files. You can do this
-		 *        using
-		 *        SceneManager-&gt;getParameters()-&gt;setAttribute(scene::MY3D_TEXTURE_PATH,
-		 *        &quot;path/to/your/textures&quot;);
+		 *        the whole My3DTools package.
 		 *        </TD>
 		 *    </TR>
 		 *    <TR>
@@ -331,11 +320,7 @@ namespace scene
 		 *      <TD>LMTools is a set of tools (Windows &amp; Linux) for
 		 *        creating lightmaps. Irrlicht can directly read .lmts
 		 *        files thanks to<br> the importer created by Jonas
-		 *        Petersen. If you are using this loader, please note
-		 *        that you can set the path of the textures before
-		 *        loading .lmts files. You can do this using
-		 *        SceneManager-&gt;getParameters()-&gt;setAttribute(scene::LMTS_TEXTURE_PATH,
-		 *        &quot;path/to/your/textures&quot;);
+		 *        Petersen.
 		 *        Notes for<br> this version of the loader:<br>
 		 *        - It does not recognise/support user data in the
 		 *          *.lmts files.<br>
@@ -1433,10 +1418,7 @@ namespace scene
 
 		//! Get interface to the parameters set in this scene.
 		/** String parameters can be used by plugins and mesh loaders.
-		For example the CMS and LMTS loader want a parameter named 'CSM_TexturePath'
-		and 'LMTS_TexturePath' set to the path were attached textures can be found. See
-		CSM_TEXTURE_PATH, LMTS_TEXTURE_PATH, MY3D_TEXTURE_PATH,
-		COLLADA_CREATE_SCENE_INSTANCES, DMF_TEXTURE_PATH and DMF_USE_MATERIALS_DIRS*/
+		See	COLLADA_CREATE_SCENE_INSTANCES and DMF_USE_MATERIALS_DIRS */
 		virtual io::IAttributes* getParameters() = 0;
 
 		//! Get current render pass.

include/SceneParameters.h

@@ -29,24 +29,24 @@ namespace scene
 	**/
 	const c8* const ALLOW_ZWRITE_ON_TRANSPARENT = "Allow_ZWrite_On_Transparent";
 
-	//! Name of the parameter for changing the texture path of the built-in csm loader.
-	/** Use it like this:
+	//! Deprecated, use IMeshLoader::getMeshTextureLoader()->setTexturePath instead.
+	/** Was used for changing the texture path of the built-in csm loader like this:
 	\code
 	SceneManager->getParameters()->setAttribute(scene::CSM_TEXTURE_PATH, "path/to/your/textures");
 	\endcode
 	**/
 	const c8* const CSM_TEXTURE_PATH = "CSM_TexturePath";
 
-	//! Name of the parameter for changing the texture path of the built-in lmts loader.
-	/** Use it like this:
+	//! Deprecated, use IMeshLoader::getMeshTextureLoader()->setTexturePath instead.
+	/** Was used for changing the texture path of the built-in lmts loader like this:
 	\code
 	SceneManager->getParameters()->setAttribute(scene::LMTS_TEXTURE_PATH, "path/to/your/textures");
 	\endcode
 	**/
 	const c8* const LMTS_TEXTURE_PATH = "LMTS_TexturePath";
 
-	//! Name of the parameter for changing the texture path of the built-in my3d loader.
-	/** Use it like this:
+	//! Deprecated, use IMeshLoader::getMeshTextureLoader()->setTexturePath instead.
+	/** Was used for changing the texture path of the built-in MY3D loader like this:
 	\code
 	SceneManager->getParameters()->setAttribute(scene::MY3D_TEXTURE_PATH, "path/to/your/textures");
 	\endcode
@@ -66,7 +66,7 @@ namespace scene
 	*/
 	const c8* const COLLADA_CREATE_SCENE_INSTANCES = "COLLADA_CreateSceneInstances";
 
-	//! Name of the parameter for changing the texture path of the built-in DMF loader.
+	//! Deprecated, use IMeshLoader::getMeshTextureLoader()->setTexturePath instead.
 	/** This path is prefixed to the file names defined in the Deled file when loading
 	textures. This allows to alter the paths for a specific project setting.
 	Use it like this:
@@ -111,8 +111,8 @@ namespace scene
 	const c8* const DMF_FLIP_ALPHA_TEXTURES = "DMF_FlipAlpha";
 
 
-	//! Name of the parameter for changing the texture path of the built-in obj loader.
-	/** Use it like this:
+	//! Deprecated, use IMeshLoader::getMeshTextureLoader()->setTexturePath instead.
+	/** Was used for changing the texture path of the built-in obj loader like this:
 	\code
 	SceneManager->getParameters()->setAttribute(scene::OBJ_TEXTURE_PATH, "path/to/your/textures");
 	\endcode
@@ -145,8 +145,8 @@ namespace scene
 	**/
 	const c8* const B3D_LOADER_IGNORE_MIPMAP_FLAG = "B3D_IgnoreMipmapFlag";
 
-	//! Name of the parameter for changing the texture path of the built-in b3d loader.
-	/** Use it like this:
+	//! Deprecated, use IMeshLoader::getMeshTextureLoader()->setTexturePath instead.
+	/** Was used for changing the texture path of the built-in b3d loader like this:
 	\code
 	SceneManager->getParameters()->setAttribute(scene::B3D_TEXTURE_PATH, "path/to/your/textures");
 	\endcode