ruby-ogre 0.0.1-x86-linux

data/deps/include/OGRE/Terrain/OgreTerrain.h

@@ -0,0 +1,2076 @@
+/*
+-----------------------------------------------------------------------------
+This source file is part of OGRE
+(Object-oriented Graphics Rendering Engine)
+For the latest info, see http://www.ogre3d.org/
+
+Copyright (c) 2000-2012 Torus Knot Software Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-----------------------------------------------------------------------------
+*/
+
+#ifndef __Ogre_Terrain_H__
+#define __Ogre_Terrain_H__
+
+#include "OgreTerrainPrerequisites.h"
+#include "OgreCommon.h"
+#include "OgreVector3.h"
+#include "OgreAxisAlignedBox.h"
+#include "OgreSceneManager.h"
+#include "OgreTerrainMaterialGenerator.h"
+#include "OgreTerrainLayerBlendMap.h"
+#include "OgreWorkQueue.h"
+
+namespace Ogre
+{
+	/** \addtogroup Optional Components
+	*  @{
+	*/
+	/** \addtogroup Terrain
+	*  Some details on the terrain component
+	*  @{
+	*/
+
+	/** The main containing class for a chunk of terrain.
+	@par
+		Terrain can be edited and stored.
+	The data format for this in a file is:<br/>
+	<b>TerrainData (Identifier 'TERR')</b>\n
+	[Version 1]
+	<table>
+	<tr>
+		<td><b>Name</b></td>
+		<td><b>Type</b></td>
+		<td><b>Description</b></td>
+	</tr>
+	<tr>
+		<td>Terrain orientation</td>
+		<td>uint8</td>
+		<td>The orientation of the terrain; XZ = 0, XY = 1, YZ = 2</td>
+	</tr>
+	<tr>
+		<td>Terrain size</td>
+		<td>uint16</td>
+		<td>The number of vertices along one side of the terrain</td>
+	</tr>
+	<tr>
+		<td>Terrain world size</td>
+		<td>Real</td>
+		<td>The world size of one side of the terrain</td>
+	</tr>
+	<tr>
+		<td>Max batch size</td>
+		<td>uint16</td>
+		<td>The maximum batch size in vertices along one side</td>
+	</tr>
+	<tr>
+		<td>Min batch size</td>
+		<td>uint16</td>
+		<td>The minimum batch size in vertices along one side</td>
+	</tr>
+	<tr>
+		<td>Position</td>
+		<td>Vector3</td>
+		<td>The location of the centre of the terrain</td>
+	</tr>
+	<tr>
+		<td>Height data</td>
+		<td>float[size*size]</td>
+		<td>List of floating point heights</td>
+	</tr>
+	<tr>
+		<td>LayerDeclaration</td>
+		<td>LayerDeclaration*</td>
+		<td>The layer declaration for this terrain (see below)</td>
+	</tr>
+	<tr>
+		<td>Layer count</td>
+		<td>uint8</td>
+		<td>The number of layers in this terrain</td>
+	</tr>
+	<tr>
+		<td>LayerInstance list</td>
+		<td>LayerInstance*</td>
+		<td>A number of LayerInstance definitions based on layer count (see below)</td>
+	</tr>
+	<tr>
+		<td>Layer blend map size</td>
+		<td>uint16</td>
+		<td>The size of the layer blend maps as stored in this file</td>
+	</tr>
+	<tr>
+		<td>Packed blend texture data</td>
+		<td>uint8*</td>
+		<td>layerCount-1 sets of blend texture data interleaved as either RGB or RGBA 
+			depending on layer count</td>
+	</tr>
+	<tr>
+		<td>Optional derived map data</td>
+		<td>TerrainDerivedMap list</td>
+		<td>0 or more sets of map data derived from the original terrain</td>
+	</tr>
+	<tr>
+		<td>Delta data</td>
+		<td>float[size*size]</td>
+		<td>At each vertex, delta information for the LOD at which this vertex disappears</td>
+	</tr>
+	<tr>
+		<td>Quadtree delta data</td>
+		<td>float[quadtrees*lods]</td>
+		<td>At each quadtree node, for each lod a record of the max delta value in the region</td>
+	</tr>
+	</table>
+	<b>TerrainLayerDeclaration (Identifier 'TDCL')</b>\n
+	[Version 1]
+	<table>
+	<tr>
+		<td><b>Name</b></td>
+		<td><b>Type</b></td>
+		<td><b>Description</b></td>
+	</tr>
+	<tr>
+		<td>TerrainLayerSampler Count</td>
+		<td>uint8</td>
+		<td>Number of samplers in this declaration</td>
+	</tr>
+	<tr>
+		<td>TerrainLayerSampler List</td>
+		<td>TerrainLayerSampler*</td>
+		<td>List of TerrainLayerSampler structures</td>
+	</tr>
+	<tr>
+		<td>Sampler Element Count</td>
+		<td>uint8</td>
+		<td>Number of sampler elements in this declaration</td>
+	</tr>
+	<tr>
+		<td>TerrainLayerSamplerElement List</td>
+		<td>TerrainLayerSamplerElement*</td>
+		<td>List of TerrainLayerSamplerElement structures</td>
+	</tr>
+	</table>
+	<b>TerrainLayerSampler (Identifier 'TSAM')</b>\n
+	[Version 1]
+	<table>
+	<tr>
+		<td><b>Name</b></td>
+		<td><b>Type</b></td>
+		<td><b>Description</b></td>
+	</tr>
+	<tr>
+		<td>Alias</td>
+		<td>String</td>
+		<td>Alias name of this sampler</td>
+	</tr>
+	<tr>
+		<td>Format</td>
+		<td>uint8</td>
+		<td>Desired pixel format</td>
+	</tr>
+	</table>
+	<b>TerrainLayerSamplerElement (Identifier 'TSEL')</b>\n
+	[Version 1]
+	<table>
+	<tr>
+		<td><b>Name</b></td>
+		<td><b>Type</b></td>
+		<td><b>Description</b></td>
+	</tr>
+	<tr>
+		<td>Source</td>
+		<td>uint8</td>
+		<td>Sampler source index</td>
+	</tr>
+	<tr>
+		<td>Semantic</td>
+		<td>uint8</td>
+		<td>Semantic interpretation of this element</td>
+	</tr>
+	<tr>
+		<td>Element start</td>
+		<td>uint8</td>
+		<td>Start of this element in the sampler</td>
+	</tr>
+	<tr>
+		<td>Element count</td>
+		<td>uint8</td>
+		<td>Number of elements in the sampler used by this entry</td>
+	</tr>
+	</table>
+	<b>LayerInstance (Identifier 'TLIN')</b>\n
+	[Version 1]
+	<table>
+	<tr>
+		<td><b>Name</b></td>
+		<td><b>Type</b></td>
+		<td><b>Description</b></td>
+	</tr>
+	<tr>
+		<td>World size</td>
+		<td>Real</td>
+		<td>The world size of this layer (determines UV scaling)</td>
+	</tr>
+	<tr>
+		<td>Texture list</td>
+		<td>String*</td>
+		<td>List of texture names corresponding to the number of samplers in the layer declaration</td>
+	</tr>
+	</table>
+	<b>TerrainDerivedData (Identifier 'TDDA')</b>\n
+	[Version 1]
+	<table>
+	<tr>
+		<td><b>Name</b></td>
+		<td><b>Type</b></td>
+		<td><b>Description</b></td>
+	</tr>
+	<tr>
+		<td>Derived data type name</td>
+		<td>String</td>
+		<td>Name of the derived data type ('normalmap', 'lightmap', 'colourmap', 'compositemap')</td>
+	</tr>
+	<tr>
+		<td>Size</td>
+		<td>uint16</td>
+		<td>Size of the data along one edge</td>
+	</tr>
+	<tr>
+		<td>Data</td>
+		<td>varies based on type</td>
+		<td>The data</td>
+	</tr>
+	</table>
+	*/
+	class _OgreTerrainExport Terrain : public SceneManager::Listener, 
+		public WorkQueue::RequestHandler, public WorkQueue::ResponseHandler, public TerrainAlloc
+	{
+	public:
+		/** Constructor.
+		@param sm The SceneManager to use.
+		*/
+		Terrain(SceneManager* sm);
+		virtual ~Terrain();
+
+		static const uint32 TERRAIN_CHUNK_ID;
+		static const uint16 TERRAIN_CHUNK_VERSION;
+		static const uint16 TERRAIN_MAX_BATCH_SIZE;
+
+		static const uint32 TERRAINLAYERDECLARATION_CHUNK_ID;
+		static const uint16 TERRAINLAYERDECLARATION_CHUNK_VERSION;
+		static const uint32 TERRAINLAYERSAMPLER_CHUNK_ID;
+		static const uint16 TERRAINLAYERSAMPLER_CHUNK_VERSION;
+		static const uint32 TERRAINLAYERSAMPLERELEMENT_CHUNK_ID;
+		static const uint16 TERRAINLAYERSAMPLERELEMENT_CHUNK_VERSION;
+		static const uint32 TERRAINLAYERINSTANCE_CHUNK_ID;
+		static const uint16 TERRAINLAYERINSTANCE_CHUNK_VERSION;
+		static const uint32 TERRAINDERIVEDDATA_CHUNK_ID;
+		static const uint16 TERRAINDERIVEDDATA_CHUNK_VERSION;
+
+		static const size_t LOD_MORPH_CUSTOM_PARAM;
+
+		typedef vector<Real>::type RealVector;
+
+		/** An instance of a layer, with specific texture names
+		*/
+		struct _OgreTerrainExport LayerInstance
+		{
+			/// The world size of the texture to be applied in this layer
+			Real worldSize;
+			/// List of texture names to import; must match with TerrainLayerDeclaration
+			StringVector textureNames;
+
+			LayerInstance()
+				: worldSize(100) {}
+		};
+		typedef vector<LayerInstance>::type LayerInstanceList;
+
+		/// The alignment of the terrain
+		enum Alignment
+		{
+			/// Terrain is in the X/Z plane
+			ALIGN_X_Z = 0, 
+			/// Terrain is in the X/Y plane
+			ALIGN_X_Y = 1, 
+			/// Terrain is in the Y/Z plane
+			ALIGN_Y_Z = 2
+		};
+
+		/** Structure encapsulating import data that you may use to bootstrap 
+			the terrain without loading from a native data stream. 
+		*/
+		struct ImportData
+		{
+			/// The alignment of the terrain
+			Alignment terrainAlign;
+			/// Terrain size (along one edge) in vertices; must be 2^n+1
+			uint16 terrainSize;
+			/** Maximum batch size (along one edge) in vertices; must be 2^n+1 and <= 65
+			@remarks
+				The terrain will be divided into hierarchical tiles, and this is the maximum
+				size of one tile in vertices (at any LOD).
+			*/
+			uint16 maxBatchSize;
+			/** Minimum batch size (along one edge) in vertices; must be 2^n+1.
+			@remarks
+			The terrain will be divided into tiles, and this is the minimum
+			size of one tile in vertices (at any LOD). Adjacent tiles will be
+			collected together into one batch to drop LOD levels once they are individually at this minimum,
+			so setting this value higher means greater batching at the expense
+			of making adjacent tiles use a common LOD.
+			Once the entire terrain is collected together into one batch this 
+			effectively sets the minimum LOD.
+			*/
+			uint16 minBatchSize;
+
+			/** Position of the terrain.
+			@remarks
+				Represents the position of the centre of the terrain. 
+			*/
+			Vector3 pos;
+
+			/** The world size of the terrain. */
+			Real worldSize;
+
+			/** Optional heightmap providing the initial heights for the terrain. 
+			@remarks
+				If supplied, should ideally be terrainSize * terrainSize, but if
+				it isn't it will be resized.
+			*/
+			Image* inputImage;
+
+			/** Optional list of terrainSize * terrainSize floats defining the terrain. 
+				The list of floats wil be interpreted such that the first row
+				in the array equates to the bottom row of vertices. 
+			*/
+			float* inputFloat;
+
+			/** If neither inputImage or inputFloat are supplied, the constant
+				height at which the initial terrain should be created (flat). 
+			*/
+			float constantHeight;
+
+			/** Whether this structure should 'own' the input data (inputImage and
+				inputFloat), and therefore delete it on destruction. 
+				The default is false so you have to manage your own memory. If you
+				set it to true, then you must have allocated the memory through
+				OGRE_NEW (for Image) and OGRE_ALLOC_T (for inputFloat), the latter
+				with the category MEMCATEGORY_GEOMETRY.
+			*/
+			bool deleteInputData;
+
+			/// How to scale the input values provided (if any)
+			Real inputScale;
+			/// How to bias the input values provided (if any)
+			Real inputBias;
+
+			/** Definition of the contents of each layer (required).
+			Most likely,  you will pull a declaration from a TerrainMaterialGenerator
+			of your choice.
+			*/
+			TerrainLayerDeclaration layerDeclaration;
+			/** List of layer structures, one for each layer required.
+				Can be empty or underfilled if required, list will be padded with
+				blank textures.
+			*/
+			LayerInstanceList layerList;
+
+			ImportData() 
+				: terrainAlign(ALIGN_X_Z)
+				, terrainSize(1025)
+				, maxBatchSize(65)
+				, minBatchSize(17)
+				, pos(Vector3::ZERO)
+				, worldSize(1000)
+				, inputImage(0)
+				, inputFloat(0)
+				, constantHeight(0)
+				, deleteInputData(false)
+				, inputScale(1.0)
+				, inputBias(0.0)
+			{
+
+			}
+
+			ImportData(const ImportData& rhs)
+				: terrainAlign(ALIGN_X_Z)
+				, terrainSize(1025)
+				, maxBatchSize(65)
+				, minBatchSize(17)
+				, pos(Vector3::ZERO)
+				, worldSize(1000)
+				, inputImage(0)
+				, inputFloat(0)
+				, constantHeight(0)
+				, deleteInputData(false)
+				, inputScale(1.0)
+				, inputBias(0.0)
+			{
+				*this = rhs;
+			}
+
+			ImportData& operator=(const ImportData& rhs)
+			{
+				// basic copy
+				terrainAlign = rhs.terrainAlign;
+				terrainSize = rhs.terrainSize;
+				maxBatchSize = rhs.maxBatchSize;
+				minBatchSize = rhs.minBatchSize;
+				pos = rhs.pos;
+				worldSize = rhs.worldSize;
+				constantHeight = rhs.constantHeight;
+				deleteInputData = rhs.deleteInputData;
+				inputScale = rhs.inputScale;
+				inputBias = rhs.inputBias;
+				layerDeclaration = rhs.layerDeclaration;
+				layerList = rhs.layerList;
+
+				// By-value copies in ownership cases
+				if (rhs.deleteInputData)
+				{
+					if (rhs.inputImage)
+						inputImage = OGRE_NEW Image(*rhs.inputImage);
+					else
+						inputImage = 0;
+
+					if (rhs.inputFloat)
+					{
+						inputFloat = OGRE_ALLOC_T(float, terrainSize*terrainSize, MEMCATEGORY_GEOMETRY);
+						memcpy(inputFloat, rhs.inputFloat, sizeof(float) * terrainSize*terrainSize);
+					}
+					else
+						inputFloat = 0;
+				}
+				else
+				{
+					// re-use pointers
+					inputImage = rhs.inputImage;
+					inputFloat = rhs.inputFloat;
+				}
+				return *this;
+			}
+
+			/// Delete any input data if this struct is set to do so
+			void destroy()
+			{
+				if (deleteInputData)
+				{
+					OGRE_DELETE inputImage;
+					OGRE_FREE(inputFloat, MEMCATEGORY_GEOMETRY);
+					inputImage = 0;
+					inputFloat = 0;
+				}
+
+			}
+
+			~ImportData()
+			{
+				destroy();
+			}
+
+		};
+
+		/// Neighbour index enumeration - indexed anticlockwise from East like angles
+		enum NeighbourIndex
+		{
+			NEIGHBOUR_EAST = 0, 
+			NEIGHBOUR_NORTHEAST = 1, 
+			NEIGHBOUR_NORTH = 2, 
+			NEIGHBOUR_NORTHWEST = 3, 
+			NEIGHBOUR_WEST = 4, 
+			NEIGHBOUR_SOUTHWEST = 5, 
+			NEIGHBOUR_SOUTH = 6, 
+			NEIGHBOUR_SOUTHEAST = 7,
+
+			NEIGHBOUR_COUNT = 8
+		};
+
+		SceneManager* getSceneManager() const { return mSceneMgr; }
+
+		/// Enumeration of relative spaces that you might want to use to address the terrain
+		enum Space
+		{
+			/// Simple global world space, axes and positions are all in world space
+			WORLD_SPACE = 0, 
+			/// As world space, but positions are relative to the terrain world position
+			LOCAL_SPACE = 1, 
+			/** x & y are parametric values on the terrain from 0 to 1, with the
+			origin at the bottom left. z is the world space height at that point.
+			*/
+			TERRAIN_SPACE = 2,
+			/** x & y are integer points on the terrain from 0 to size-1, with the
+			origin at the bottom left. z is the world space height at that point.
+			*/
+			POINT_SPACE = 3
+		};
+
+		/** Interface used to by the Terrain instance to allocate GPU buffers.
+		@remarks This class exists to make it easier to re-use buffers between
+			multiple instances of terrain.
+		*/
+		class _OgreTerrainExport GpuBufferAllocator : public TerrainAlloc
+		{
+		public:
+			GpuBufferAllocator() {}
+			virtual ~GpuBufferAllocator() {}
+
+			/** Allocate (or reuse) vertex buffers for a terrain LOD. 
+			@param numVertices The total number of vertices
+			@param destPos Pointer to a vertex buffer for positions, to be bound
+			@param destDelta Pointer to a vertex buffer for deltas, to be bound
+			*/
+			virtual void allocateVertexBuffers(Terrain* forTerrain, size_t numVertices, HardwareVertexBufferSharedPtr& destPos, HardwareVertexBufferSharedPtr& destDelta) = 0;
+			/** Free (or return to the pool) vertex buffers for terrain. 
+			*/
+			virtual void freeVertexBuffers(const HardwareVertexBufferSharedPtr& posbuf, const HardwareVertexBufferSharedPtr& deltabuf) = 0;
+
+			/** Get a shared index buffer for a given number of settings.
+			@remarks
+				Since all index structures are the same at the same LOD level and
+				relative position, we can share index buffers. Therefore the 
+				buffer returned from this method does not need to be 'freed' like
+				the vertex buffers since it is never owned.
+			@param batchSize The batch size along one edge
+			@param vdatasize The size of the referenced vertex data along one edge
+			@param vertexIncrement The number of vertices to increment for each new indexed row / column
+			@param xoffset The x offset from the start of vdatasize, at that resolution
+			@param yoffset The y offset from the start of vdatasize, at that resolution
+			@param numSkirtRowsCols Number of rows and columns of skirts
+			@param skirtRowColSkip The number of rows / cols to skip in between skirts
+			*/
+			virtual HardwareIndexBufferSharedPtr getSharedIndexBuffer(uint16 batchSize, 
+				uint16 vdatasize, size_t vertexIncrement, uint16 xoffset, uint16 yoffset, uint16 numSkirtRowsCols, 
+				uint16 skirtRowColSkip) = 0;
+
+			/// Free any buffers we're holding
+			virtual void freeAllBuffers() = 0;
+
+		};
+		/// Standard implementation of a buffer allocator which re-uses buffers
+		class _OgreTerrainExport DefaultGpuBufferAllocator : public GpuBufferAllocator
+		{
+		public:
+			DefaultGpuBufferAllocator();
+			~DefaultGpuBufferAllocator();
+			void allocateVertexBuffers(Terrain* forTerrain, size_t numVertices, HardwareVertexBufferSharedPtr& destPos, HardwareVertexBufferSharedPtr& destDelta);
+			void freeVertexBuffers(const HardwareVertexBufferSharedPtr& posbuf, const HardwareVertexBufferSharedPtr& deltabuf);
+			HardwareIndexBufferSharedPtr getSharedIndexBuffer(uint16 batchSize, 
+				uint16 vdatasize, size_t vertexIncrement, uint16 xoffset, uint16 yoffset, uint16 numSkirtRowsCols, 
+				uint16 skirtRowColSkip);
+			void freeAllBuffers();
+
+			/** 'Warm start' the allocator based on needing x instances of 
+				terrain with the given configuration.
+			*/
+			void warmStart(size_t numInstances, uint16 terrainSize, uint16 maxBatchSize, 
+				uint16 minBatchSize);
+
+		protected:
+			typedef list<HardwareVertexBufferSharedPtr>::type VBufList;
+			VBufList mFreePosBufList;
+			VBufList mFreeDeltaBufList;
+			typedef map<uint32, HardwareIndexBufferSharedPtr>::type IBufMap;
+			IBufMap mSharedIBufMap;
+
+			uint32 hashIndexBuffer(uint16 batchSize, 
+				uint16 vdatasize, size_t vertexIncrement, uint16 xoffset, uint16 yoffset, uint16 numSkirtRowsCols, 
+				uint16 skirtRowColSkip);
+			HardwareVertexBufferSharedPtr getVertexBuffer(VBufList& list, size_t vertexSize, size_t numVertices);
+
+		};
+
+		/** Tell this instance to use the given GpuBufferAllocator. 
+		@remarks
+			May only be called when the terrain is not loaded.
+		*/
+		void setGpuBufferAllocator(GpuBufferAllocator* alloc);
+
+		/// Get the current buffer allocator
+		GpuBufferAllocator* getGpuBufferAllocator();
+
+		/// Utility method to get the number of indexes required to render a given batch
+		static size_t _getNumIndexesForBatchSize(uint16 batchSize);
+		/** Utility method to populate a (locked) index buffer.
+		@param pIndexes Pointer to an index buffer to populate
+		@param batchSize The number of vertices down one side of the batch
+		@param vdatasize The number of vertices down one side of the vertex data being referenced
+		@param vertexIncrement The number of vertices to increment for each new indexed row / column
+		@param xoffset The x offset from the start of the vertex data being referenced
+		@param yoffset The y offset from the start of the vertex data being referenced
+		@param numSkirtRowsCols Number of rows and columns of skirts
+		@param skirtRowColSkip The number of rows / cols to skip in between skirts
+
+		*/
+		static void _populateIndexBuffer(uint16* pIndexes, uint16 batchSize, 
+			uint16 vdatasize, size_t vertexIncrement, uint16 xoffset, uint16 yoffset, uint16 numSkirtRowsCols, 
+			uint16 skirtRowColSkip);
+
+		/** Utility method to calculate the skirt index for a given original vertex index. */
+		static uint16 _calcSkirtVertexIndex(uint16 mainIndex, uint16 vdatasize, bool isCol, 
+			uint16 numSkirtRowsCols, uint16 skirtRowColSkip);
+
+		/** Convert a position from one space to another with respect to this terrain.
+		@param inSpace The space that inPos is expressed as
+		@param inPos The incoming position
+		@param outSpace The space which outPos should be expressed as
+		@param outPos The output position to be populated
+		*/
+		void convertPosition(Space inSpace, const Vector3& inPos, Space outSpace, Vector3& outPos) const;
+		/** Convert a position from one space to another with respect to this terrain.
+		@param inSpace The space that inPos is expressed as
+		@param inPos The incoming position
+		@param outSpace The space which outPos should be expressed as
+		@return The output position 
+		*/
+		Vector3 convertPosition(Space inSpace, const Vector3& inPos, Space outSpace) const;
+		/** Convert a direction from one space to another with respect to this terrain.
+		@param inSpace The space that inDir is expressed as
+		@param inDir The incoming direction
+		@param outSpace The space which outDir should be expressed as
+		@param outDir The output direction to be populated
+		*/
+		void convertDirection(Space inSpace, const Vector3& inDir, Space outSpace, Vector3& outDir) const;
+		/** Convert a direction from one space to another with respect to this terrain.
+		@param inSpace The space that inDir is expressed as
+		@param inDir The incoming direction
+		@param outSpace The space which outDir should be expressed as
+		@return The output direction 
+		*/
+		Vector3 convertDirection(Space inSpace, const Vector3& inDir, Space outSpace) const;
+
+		/** Set the resource group to use when loading / saving. 
+		@param resGroup Resource group name - you can set this to blank to use
+			the default in TerrainGlobalOptions.
+		*/
+		void setResourceGroup(const String& resGroup) { mResourceGroup = resGroup; }
+
+		/** Get the resource group to use when loading / saving. 
+			If this is blank, the default in TerrainGlobalOptions will be used.
+		*/
+		const String& getResourceGroup() const { return mResourceGroup; }
+
+		/** Get the final resource group to use when loading / saving. 
+		*/
+		const String& _getDerivedResourceGroup() const;
+
+		/** Save terrain data in native form to a standalone file
+		@param filename The name of the file to save to. If this is a filename with
+			no path elements, then it is saved in the first writeable location
+			available in the resource group you have chosen to use for this
+			terrain. If the filename includes path specifiers then it is saved
+			directly instead (but note that it may not be reloadable via the
+			resource system if the location is not on the path). 
+		*/
+		void save(const String& filename);
+		/** Save terrain data in native form to a serializing stream.
+		@remarks
+			If you want complete control over where the terrain data goes, use
+			this form.
+		*/
+		void save(StreamSerialiser& stream);
+
+		/** Prepare the terrain from a standalone file.
+		@note
+		This is safe to do in a background thread as it creates no GPU resources.
+		It reads data from a native terrain data chunk. For more advanced uses, 
+		such as loading from a shared file, use the StreamSerialiser form.
+		*/
+		bool prepare(const String& filename);
+		/** Prepare terrain data from saved data.
+		@remarks
+			This is safe to do in a background thread as it creates no GPU resources.
+			It reads data from a native terrain data chunk. 
+		@return true if the preparation was successful
+		*/
+		bool prepare(StreamSerialiser& stream);
+
+		/** Prepare the terrain from some import data rather than loading from 
+			native data. 
+		@remarks
+			This method may be called in a background thread.
+		*/
+		bool prepare(const ImportData& importData);
+
+		/** Prepare and load the terrain in one simple call from a standalone file.
+		@note
+			This method must be called from the primary render thread. To load data
+			in a background thread, use the prepare() method.
+		*/
+		void load(const String& filename);
+
+		/** Prepare and load the terrain in one simple call from a stream.
+		@note
+		This method must be called from the primary render thread. To load data
+		in a background thread, use the prepare() method.
+		*/
+		void load(StreamSerialiser& stream);
+
+		/** Load the terrain based on the data already populated via prepare methods. 
+		@remarks
+			This method must be called in the main render thread. 
+		*/
+		void load();
+
+		/** Return whether the terrain is loaded. 
+		@remarks
+			Should only be called from the render thread really, since this is
+			where the loaded state changes.
+		*/
+		bool isLoaded() const { return mIsLoaded; }
+
+		/** Returns whether this terrain has been modified since it was first loaded / defined. 
+		@remarks
+			This flag is reset on save().
+		*/
+		bool isModified() const { return mModified; }
+
+
+		/** Returns whether terrain heights have been modified since the terrain was first loaded / defined. 
+		@remarks
+		This flag is reset on save().
+		*/
+		bool isHeightDataModified() const { return mHeightDataModified; }
+
+
+		/** Unload the terrain and free GPU resources. 
+		@remarks
+			This method must be called in the main render thread.
+		*/
+		void unload();
+
+		/** Free CPU resources created during prepare methods.
+		@remarks
+			This is safe to do in a background thread after calling unload().
+		*/
+		void unprepare();
+
+
+		/** Get a pointer to all the height data for this terrain.
+		@remarks
+			The height data is in world coordinates, relative to the position 
+			of the terrain.
+		@par
+			This pointer is not const, so you can update the height data if you
+			wish. However, changes will not be propagated until you call 
+			Terrain::dirty or Terrain::dirtyRect.
+		*/
+		float* getHeightData() const;
+
+		/** Get a pointer to the height data for a given point. 
+		*/
+		float* getHeightData(long x, long y) const;
+
+		/** Get the height data for a given terrain point. 
+		@param x, y Discrete coordinates in terrain vertices, values from 0 to size-1,
+			left/right bottom/top
+		*/
+		float getHeightAtPoint(long x, long y) const;
+
+		/** Set the height data for a given terrain point. 
+		@note this doesn't take effect until you call update()
+		@param x, y Discrete coordinates in terrain vertices, values from 0 to size-1,
+		left/right bottom/top
+		@param h The new height
+		*/
+		void setHeightAtPoint(long x, long y, float h);
+
+		/** Get the height data for a given terrain position. 
+		@param x, y Position in terrain space, values from 0 to 1 left/right bottom/top
+		*/
+		float getHeightAtTerrainPosition(Real x, Real y);
+
+		/** Get the height data for a given world position (projecting the point
+			down on to the terrain). 
+		@param x, y,z Position in world space. Positions will be clamped to the edge
+			of the terrain
+		*/
+		float getHeightAtWorldPosition(Real x, Real y, Real z);
+
+		/** Get the height data for a given world position (projecting the point
+		down on to the terrain). 
+		@param pos Position in world space. Positions will be clamped to the edge
+		of the terrain
+		*/
+		float getHeightAtWorldPosition(const Vector3& pos);
+
+		/** Get a pointer to all the delta data for this terrain.
+		@remarks
+			The delta data is a measure at a given vertex of by how much vertically
+			a vertex will have to move to reach the point at which it will be
+			removed in the next lower LOD.
+		*/
+		const float* getDeltaData();
+
+		/** Get a pointer to the delta data for a given point. 
+		*/
+		const float* getDeltaData(long x, long y);
+
+		/** Get a Vector3 of the world-space point on the terrain, aligned as per
+			options.
+		@note This point is relative to Terrain::getPosition
+		*/
+		void getPoint(long x, long y, Vector3* outpos);
+
+		/** Get a Vector3 of the world-space point on the terrain, aligned as per
+		options. Cascades into neighbours if out of bounds.
+		@note This point is relative to Terrain::getPosition - neighbours are
+			adjusted to be relative to this tile
+		*/
+		void getPointFromSelfOrNeighbour(long x, long y, Vector3* outpos);
+
+		/** Get a Vector3 of the world-space point on the terrain, supplying the
+			height data manually (can be more optimal). 
+		@note This point is relative to Terrain::getPosition
+		*/
+		void getPoint(long x, long y, float height, Vector3* outpos);
+		/** Get a transform which converts Vector4(xindex, yindex, height, 1) into 
+			an object-space position including scalings and alignment.
+		*/
+		void getPointTransform(Matrix4* outXform) const;
+		/** Translate a vector from world space to local terrain space based on the alignment options.
+		@param inVec The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getTerrainVector(const Vector3& inVec, Vector3* outVec);
+		/** Translate a vector from world space to local terrain space based on a specified alignment.
+		@param inVec The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getTerrainVectorAlign(const Vector3& inVec, Alignment align, Vector3* outVec);
+
+		/** Translate a vector from world space to local terrain space based on the alignment options.
+		@param x, y, z The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getTerrainVector(Real x, Real y, Real z, Vector3* outVec);
+		/** Translate a vector from world space to local terrain space based on a specified alignment.
+		@param x, y, z The vector in world space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getTerrainVectorAlign(Real x, Real y, Real z, Alignment align, Vector3* outVec);
+
+		/** Translate a vector into world space based on the alignment options.
+		@param inVec The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getVector(const Vector3& inVec, Vector3* outVec);
+		/** Translate a vector into world space based on a specified alignment.
+		@param inVec The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getVectorAlign(const Vector3& inVec, Alignment align, Vector3* outVec);
+
+		/** Translate a vector into world space based on the alignment options.
+		@param x, y, z The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getVector(Real x, Real y, Real z, Vector3* outVec);
+		/** Translate a vector into world space based on a specified alignment.
+		@param x, y, z The vector in basis space, where x/y represents the 
+		terrain plane and z represents the up vector
+		*/
+		void getVectorAlign(Real x, Real y, Real z, Alignment align, Vector3* outVec);
+
+
+		/** Convert a position from terrain basis space to world space. 
+		@param TSpos Terrain space position, where (0,0) is the bottom-left of the
+			terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+			height units.
+		@note This position is relative to Terrain::getPosition
+		@param outWSpos World space output position (setup according to current alignment). 
+		*/
+		void getPosition(const Vector3& TSpos, Vector3* outWSpos);
+		/** Convert a position from terrain basis space to world space. 
+		@param x,y,z Terrain space position, where (0,0) is the bottom-left of the
+		terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+		height units.
+		@note This position is relative to Terrain::getPosition
+		@param outWSpos World space output position (setup according to current alignment). 
+		*/
+		void getPosition(Real x, Real y, Real z, Vector3* outWSpos);
+
+		/** Convert a position from world space to terrain basis space. 
+		@param WSpos World space position (setup according to current alignment). 
+		@param outTSpos Terrain space output position, where (0,0) is the bottom-left of the
+		terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+		height units.
+		*/
+		void getTerrainPosition(const Vector3& WSpos, Vector3* outTSpos);
+		/** Convert a position from world space to terrain basis space. 
+		@param x,y,z World space position (setup according to current alignment). 
+		@param outTSpos Terrain space output position, where (0,0) is the bottom-left of the
+		terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+		height units.
+		*/
+		void getTerrainPosition(Real x, Real y, Real z, Vector3* outTSpos);
+		/** Convert a position from terrain basis space to world space based on a specified alignment. 
+		@param TSpos Terrain space position, where (0,0) is the bottom-left of the
+			terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+			height units.
+		@param outWSpos World space output position (setup according to alignment). 
+		*/
+		void getPositionAlign(const Vector3& TSpos, Alignment align, Vector3* outWSpos);
+		/** Convert a position from terrain basis space to world space based on a specified alignment. 
+		@param x,y,z Terrain space position, where (0,0) is the bottom-left of the
+		terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+		height units.
+		@param outWSpos World space output position (setup according to alignment). 
+		*/
+		void getPositionAlign(Real x, Real y, Real z, Alignment align, Vector3* outWSpos);
+
+		/** Convert a position from world space to terrain basis space based on a specified alignment. 
+		@param WSpos World space position (setup according to alignment). 
+		@param outTSpos Terrain space output position, where (0,0) is the bottom-left of the
+		terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+		height units.
+		*/
+		void getTerrainPositionAlign(const Vector3& WSpos, Alignment align, Vector3* outTSpos);
+		/** Convert a position from world space to terrain basis space based on a specified alignment. 
+		@param x,y,z World space position (setup according to alignment). 
+		@param outTSpos Terrain space output position, where (0,0) is the bottom-left of the
+		terrain, and (1,1) is the top-right. The Z coordinate is in absolute
+		height units.
+		*/
+		void getTerrainPositionAlign(Real x, Real y, Real z, Alignment align, Vector3* outTSpos);
+
+
+		/// Get the alignment of the terrain
+		Alignment getAlignment() const;
+		/// Get the size of the terrain in vertices along one side
+		uint16 getSize() const;
+		/** Set the size of terrain in vertices along one side. 
+		@note The existing height data will be bilinear filtered to fill the new size
+		@param newSize the new size of the terrain
+		*/
+        void setSize(uint16 newSize);
+		/// Get the maximum size in vertices along one side of a batch 
+		uint16 getMaxBatchSize() const;
+		/// Get the minimum size in vertices along one side of a batch 
+		uint16 getMinBatchSize() const;
+		/// Get the size of the terrain in world units
+		Real getWorldSize() const;
+		/** Set the world size of terrain. 
+		@param newWorldSize the new world size of the terrain
+		*/
+        void setWorldSize(Real newWorldSize);
+
+		/** Get the number of layers in this terrain. */
+		uint8 getLayerCount() const { return static_cast<uint8>(mLayers.size()); }
+
+		/** Get the declaration which describes the layers in this terrain. */
+		const TerrainLayerDeclaration& getLayerDeclaration() const { return mLayerDecl; }
+
+		/** Add a new layer to this terrain.
+		@param worldSize The size of the texture in this layer in world units. Default
+		to zero to use the default
+		@param textureNames A list of textures to assign to the samplers in this
+			layer. Leave blank to provide these later. 
+		*/
+		void addLayer(Real worldSize = 0, const StringVector* textureNames = 0);
+
+		/** Add a new layer to this terrain at a specific index.
+		@param index The index at which to insert this layer (existing layers are shifted forwards)
+		@param worldSize The size of the texture in this layer in world units. Default
+		to zero to use the default
+		@param textureNames A list of textures to assign to the samplers in this
+			layer. Leave blank to provide these later. 
+		*/
+		void addLayer(uint8 index, Real worldSize = 0, const StringVector* textureNames = 0);
+
+		/** Remove a layer from the terrain.
+		*/
+		void removeLayer(uint8 index);
+
+		/** Replace an existing terrain layer, optionally preserving all other layer blend maps
+		@param index The 0 based index of the terrain layer to replace
+		@param keepBlends True to keep using the existing blend maps.  False to reset the blend map for the layer.
+		Irrelevant if index == 0
+		@param worldSize The size of the texture in this layer in world units. Default
+		to zero to use the default
+		@param textureNames A list of textures to assign to the samplers in this
+			layer. Leave blank to provide these later. 
+		*/
+        void replaceLayer(uint8 index, bool keepBlends, Real worldSize = 0, const StringVector* textureNames = 0);
+
+		/** Get the maximum number of layers supported with the current options. 
+		@note When you change the options requested, this value can change. 
+		*/
+		uint8 getMaxLayers() const;
+
+		/** How large an area in world space the texture in a terrain layer covers
+		before repeating. 
+		@param index The layer index.
+		*/
+		Real getLayerWorldSize(uint8 index) const;
+		/** How large an area in world space the texture in a terrain layer covers
+		before repeating. 
+		@param index The layer index.
+		@param size The world size of the texture before repeating
+		*/
+		void setLayerWorldSize(uint8 index, Real size);
+
+		/** Get the layer UV multiplier. 
+		@remarks
+			This is derived from the texture world size. The base UVs in the 
+			terrain vary from 0 to 1 and this multiplier is used (in a fixed-function 
+			texture coord scaling or a shader parameter) to translate it to the
+			final value.
+		@param index The layer index.
+		*/
+		Real getLayerUVMultiplier(uint8 index) const;
+
+		/** Get the name of the texture bound to a given index within a given layer.
+		See the LayerDeclaration for a list of sampelrs within a layer.
+		@param layerIndex The layer index.
+		@param samplerIndex The sampler index within a layer
+		*/
+		const String& getLayerTextureName(uint8 layerIndex, uint8 samplerIndex) const;
+		/** Set the name of the texture bound to a given index within a given layer.
+		See the LayerDeclaration for a list of sampelrs within a layer.
+		@param index The layer index.
+		@param size The world size of the texture before repeating
+		@param textureName The name of the texture to use
+		*/
+		void setLayerTextureName(uint8 layerIndex, uint8 samplerIndex, const String& textureName);
+
+		/** Get the requested size of the blend maps used to blend between layers
+			for this terrain. 
+			Note that where hardware limits this, the actual blend maps may be lower
+			resolution. This option is derived from TerrainGlobalOptions when the
+			terrain is created.
+		*/
+		uint16 getLayerBlendMapSize() const { return mLayerBlendMapSize; }
+
+		/** Get the requested size of lightmap for this terrain. 
+		Note that where hardware limits this, the actual lightmap may be lower
+		resolution. This option is derived from TerrainGlobalOptions when the
+		terrain is created.
+		*/
+		uint16 getLightmapSize() const { return mLightmapSize; }
+
+		/// Get access to the lightmap, if enabled (as requested by the material generator)
+		const TexturePtr& getLightmap() const { return mLightmap; }
+
+		/** Get the requested size of composite map for this terrain. 
+		Note that where hardware limits this, the actual texture may be lower
+		resolution. This option is derived from TerrainGlobalOptions when the
+		terrain is created.
+		*/
+		uint16 getCompositeMapSize() const { return mCompositeMapSize; }
+
+		/// Get access to the composite map, if enabled (as requested by the material generator)
+		const TexturePtr& getCompositeMap() const { return mCompositeMap; }
+
+		/// Get the world position of the terrain centre
+		const Vector3& getPosition() const { return mPos; }
+		/// Set the position of the terrain centre in world coordinates
+		void setPosition(const Vector3& pos);
+		/// Get the root scene node for the terrain (internal use only)
+		SceneNode* _getRootSceneNode() const;
+		/** Mark the entire terrain as dirty. 
+		By marking a section of the terrain as dirty, you are stating that you have
+		changed the height data within this rectangle. This rectangle will be merged with
+		any existing outstanding changes. To finalise the changes, you must 
+		call update(), updateGeometry(), or updateDerivedData().
+		*/
+		void dirty();
+
+		/** Mark a region of the terrain as dirty. 
+		By marking a section of the terrain as dirty, you are stating that you have
+		changed the height data within this rectangle. This rectangle will be merged with
+		any existing outstanding changes. To finalise the changes, you must 
+		call update(), updateGeometry(), or updateDerivedData().
+		@param rect A rectangle expressed in vertices describing the dirty region;
+			left < right, top < bottom, left & top are inclusive, right & bottom exclusive
+		*/
+		void dirtyRect(const Rect& rect);
+
+		/** Mark a region of the terrain composite map as dirty. 
+		@remarks
+			You don't usually need to call this directly, it is inferred from 
+			changing the other data on the terrain.
+		*/
+		void _dirtyCompositeMapRect(const Rect& rect);
+
+		/** Mark a region of the lightmap as dirty.
+		@remarks
+			You only need to call this if you need to tell the terrain to update
+			the lightmap data for some reason other than the terrain geometry
+			has changed. Changing terrain geometry automatically dirties the
+			correct lightmap areas.
+		@note
+			The lightmap won't actually be updated until update() or updateDerivedData()
+			is called.
+		*/
+		void dirtyLightmapRect(const Rect& rect);
+
+		/** Mark a the entire lightmap as dirty.
+		@remarks
+			You only need to call this if you need to tell the terrain to update
+			the lightmap data for some reason other than the terrain geometry
+			has changed. Changing terrain geometry automatically dirties the
+			correct lightmap areas.
+		@note
+			The lightmap won't actually be updated until update() or updateDerivedData()
+			is called.
+		*/
+		void dirtyLightmap();
+
+		/** Trigger the update process for the terrain.
+		@remarks
+			Updating the terrain will process any dirty sections of the terrain.
+			This may affect many things:
+			<ol><li>The terrain geometry</li>
+			<li>The terrain error metrics which determine LOD transitions</li>
+			<li>The terrain normal map, if present</li>
+			<li>The terrain lighting map, if present</li>
+			<li>The terrain composite map, if present</li>
+			</ol>
+			If threading is enabled, only item 1 (the geometry) will be updated
+			synchronously, ie will be fully up to date when this method returns.
+			The other elements are more expensive to compute, and will be queued
+			for processing in a background thread, in the order shown above. As these
+			updates complete, the effects will be shown.
+
+			You can also separate the timing of updating the geometry, LOD and the lighting
+			information if you want, by calling updateGeometry() and
+			updateDerivedData() separately.
+			@param synchronous If true, all updates will happen immediately and not
+			in a separate thread.
+		*/
+		void update(bool synchronous = false);
+
+		/** Performs an update on the terrain geometry based on the dirty region.
+		@remarks
+			Terrain geometry will be updated when this method returns.
+		*/
+		void updateGeometry();
+
+		// Used as a type mask for updateDerivedData
+		static const uint8 DERIVED_DATA_DELTAS;
+		static const uint8 DERIVED_DATA_NORMALS;
+		static const uint8 DERIVED_DATA_LIGHTMAP;
+		static const uint8 DERIVED_DATA_ALL;
+
+		/** Updates derived data for the terrain (LOD, lighting) to reflect changed height data, in a separate
+		thread if threading is enabled (OGRE_THREAD_SUPPORT). 
+		If threading is enabled, on return from this method the derived
+		data will not necessarily be updated immediately, the calculation 
+		may be done in the background. Only one update will run in the background
+		at once. This derived data can typically survive being out of sync for a 
+		few frames which is why it is not done synchronously
+		@param synchronous If true, the update will happen immediately and not
+			in a separate thread.
+		@param typeMask Mask indicating the types of data we should generate
+		*/
+		void updateDerivedData(bool synchronous = false, uint8 typeMask = 0xFF);
+
+		/** Performs an update on the terrain composite map based on its dirty region.
+		@remarks
+			Rather than calling this directly, call updateDerivedData, which will
+			also call it after the other derived data has been updated (there is
+			no point updating the composite map until lighting has been updated).
+			However the blend maps may call this directly when only the blending 
+			information has been updated.
+		*/
+		void updateCompositeMap();
+
+		/** Performs an update on the terrain composite map based on its dirty region, 
+			but only at a maximum frequency. 
+		@remarks
+		Rather than calling this directly, call updateDerivedData, which will
+		also call it after the other derived data has been updated (there is
+		no point updating the composite map until lighting has been updated).
+		However the blend maps may call this directly when only the blending 
+		information has been updated.
+		@note
+		This method will log the request for an update, but won't do it just yet 
+		unless there are no further requests in the next 'delay' seconds. This means
+		you can call it all the time but only pick up changes in quiet times.
+		*/
+		void updateCompositeMapWithDelay(Real delay = 2);
+
+
+		/** The default size of 'skirts' used to hide terrain cracks
+			(default 10, set for new Terrain using TerrainGlobalOptions)
+		*/
+		Real getSkirtSize() const { return mSkirtSize; }
+
+		/// Get the total number of LOD levels in the terrain
+		uint16 getNumLodLevels() const { return mNumLodLevels; }
+
+		/// Get the number of LOD levels in a leaf of the terrain quadtree
+		uint16 getNumLodLevelsPerLeaf() const { return mNumLodLevelsPerLeafNode; }
+
+		/** Calculate (or recalculate) the delta values of heights between a vertex
+			in its recorded position, and the place it will end up in the LOD
+			in which it is removed. 
+		@param rect Rectangle describing the area in which heights have altered 
+		@return A Rectangle describing the area which was updated (may be wider
+			than the input rectangle)
+		*/
+		Rect calculateHeightDeltas(const Rect& rect);
+
+		/** Finalise the height deltas. 
+		Calculated height deltas are kept in a separate calculation field to make
+		them safe to perform in a background thread. This call promotes those
+		calculations to the runtime values, and must be called in the main thread.
+		@param rect Rectangle describing the area to finalise 
+		@param cpuData When updating vertex data, update the CPU copy (background)
+		*/
+		void finaliseHeightDeltas(const Rect& rect, bool cpuData);
+
+		/** Calculate (or recalculate) the normals on the terrain
+		@param rect Rectangle describing the area of heights that were changed
+		@param outFinalRect Output rectangle describing the area updated
+		@return Pointer to a PixelBox full of normals (caller responsible for deletion)
+		*/
+		PixelBox* calculateNormals(const Rect& rect, Rect& outFinalRect);
+
+		/** Finalise the normals. 
+		Calculated normals are kept in a separate calculation area to make
+		them safe to perform in a background thread. This call promotes those
+		calculations to the runtime values, and must be called in the main thread.
+		@param rect Rectangle describing the area to finalise 
+		@param normalsBox Pointer to a PixelBox full of normals
+		*/
+		void finaliseNormals(const Rect& rect, PixelBox* normalsBox);
+
+		/** Calculate (or recalculate) the terrain lightmap
+		@param rect Rectangle describing the area of heights that were changed
+		@param extraTargetRect Rectangle describing a target area of the terrain that
+			needs to be calculated additionally (e.g. from a neighbour)
+		@param outFinalRect Output rectangle describing the area updated in the lightmap
+		@return Pointer to a PixelBox full of lighting data (caller responsible for deletion)
+		*/
+		PixelBox* calculateLightmap(const Rect& rect, const Rect& extraTargetRect, Rect& outFinalRect);
+
+		/** Finalise the lightmap. 
+		Calculating lightmaps is kept in a separate calculation area to make
+		it safe to perform in a background thread. This call promotes those
+		calculations to the runtime values, and must be called in the main thread.
+		@param rect Rectangle describing the area to finalise 
+		@param normalsBox Pointer to a PixelBox full of normals
+		*/
+		void finaliseLightmap(const Rect& rect, PixelBox* lightmapBox);
+
+		/** Gets the resolution of the entire terrain (down one edge) at a 
+			given LOD level. 
+		*/
+		uint16 getResolutionAtLod(uint16 lodLevel);
+
+		/** Test for intersection of a given ray with the terrain. If the ray hits
+		 the terrain, the point of intersection is returned.
+		 @param ray The ray to test for intersection
+		 @param cascadeToNeighbours Whether the ray will be projected onto neighbours if
+			no intersection is found
+		 @param distanceLimit The distance from the ray origin at which we will stop looking,
+			0 indicates no limit
+		 @return A pair which contains whether the ray hit the terrain and, if so, where.
+		 @remarks This can be called from any thread as long as no parallel write to
+		 the heightmap data occurs.
+		 */
+		std::pair<bool, Vector3> rayIntersects(const Ray& ray, 
+			bool cascadeToNeighbours = false, Real distanceLimit = 0); //const;
+		
+		/// Get the AABB (local coords) of the entire terrain
+		const AxisAlignedBox& getAABB() const;
+		/// Get the AABB (world coords) of the entire terrain
+		AxisAlignedBox getWorldAABB() const;
+		/// Get the minimum height of the terrain
+		Real getMinHeight() const;
+		/// Get the maximum height of the terrain
+		Real getMaxHeight() const;
+		/// Get the bounding radius of the entire terrain
+		Real getBoundingRadius() const;
+
+		/// Get the material being used for the terrain
+		const MaterialPtr& getMaterial() const;
+		/// Internal getting of material 
+		const MaterialPtr& _getMaterial() const { return mMaterial; }
+		/// Get the material being used for the terrain composite map
+		const MaterialPtr& getCompositeMapMaterial() const;
+		/// Internal getting of material  for the terrain composite map
+		const MaterialPtr& _getCompositeMapMaterial() const { return mCompositeMapMaterial; }
+
+		/// Get the name of the material being used for the terrain
+		const String& getMaterialName() const { return mMaterialName; }
+
+		/// Overridden from SceneManager::Listener
+		void preFindVisibleObjects(SceneManager* source, 
+			SceneManager::IlluminationRenderStage irs, Viewport* v);
+		/// Overridden from SceneManager::Listener
+		void sceneManagerDestroyed(SceneManager* source);
+
+		/// Get the render queue group that this terrain will be rendered into
+		uint8 getRenderQueueGroup(void) const { return mRenderQueueGroup; }
+		/** Set the render queue group that this terrain will be rendered into.
+		@remarks The default is specified in TerrainGlobalOptions
+		*/
+		void setRenderQueueGroup(uint8 grp) { mRenderQueueGroup = grp; }
+
+		/// Get the visibility flags for this terrain.
+		uint32 getVisibilityFlags(void) const { return mVisibilityFlags; }
+		/** Set the visibility flags for this terrain.
+		@remarks The default is specified in TerrainGlobalOptions
+		*/
+		void setVisibilityFlags(uint32 flags) { mVisibilityFlags = flags; }
+
+		/// Get the query flags for this terrain.
+		uint32 getQueryFlags(void) const { return mQueryFlags; }
+		/** Set the query flags for this terrain.
+		@remarks The default is specified in TerrainGlobalOptions
+		*/
+		void setQueryFlags(uint32 flags) { mQueryFlags = flags; }
+		
+		/** As setQueryFlags, except the flags passed as parameters are appended to the existing flags on this object. */
+		void addQueryFlags(uint32 flags) { mQueryFlags |= flags; }
+		
+		/* As setQueryFlags, except the flags passed as parameters are removed from the existing flags on this object. */
+		void removeQueryFlags(uint32 flags) { mQueryFlags &= ~flags; }
+		
+
+		/** Retrieve the layer blending map for a given layer, which may
+			be used to edit the blending information for that layer.
+		@note
+			You can only do this after the terrain has been loaded. You may 
+			edit the content of the blend layer in another thread, but you
+			may only upload it in the main render thread.
+		@param layerIndex The layer index, which should be 1 or higher (since 
+			the bottom layer has no blending).
+		@return Pointer to the TerrainLayerBlendMap requested. The caller must
+			not delete this instance, use freeTemporaryResources if you want
+			to save the memory after completing your editing.
+		*/
+		TerrainLayerBlendMap* getLayerBlendMap(uint8 layerIndex);
+
+		/** Get the index of the blend texture that a given layer uses.
+		@param layerIndex The layer index, must be >= 1 and less than the number
+			of layers
+		@return The index of the shared blend texture
+		*/
+		uint8 getBlendTextureIndex(uint8 layerIndex) const;
+
+		/// Get the number of blend textures in use
+		uint8 getBlendTextureCount() const;
+		/// Get the number of blend textures needed for a given number of layers
+		uint8 getBlendTextureCount(uint8 numLayers) const;
+
+
+		/** Get the name of the packed blend texture at a specific index.
+		@param textureIndex This is the blend texture index, not the layer index
+			(multiple layers will share a blend texture)
+		*/
+		const String& getBlendTextureName(uint8 textureIndex) const;
+
+		/** Set whether a global colour map is enabled. 
+		@remarks
+			A global colour map can add variation to your terrain and reduce the 
+			perceived tiling effect you might get in areas of continuous lighting
+			and the same texture. 
+			The global colour map is only used when the material generator chooses
+			to use it.
+		@note You must only call this from the main render thread
+		@param enabled Whether the global colour map is enabled or not
+		@param size The resolution of the colour map. A value of zero means 'no change'
+			and the default is set in TerrainGlobalOptions.
+		*/
+		void setGlobalColourMapEnabled(bool enabled, uint16 size = 0);
+		/// Get whether a global colour map is enabled on this terrain
+		bool getGlobalColourMapEnabled() const { return mGlobalColourMapEnabled; }
+		/// Get the size of the global colour map (if used)
+		uint16 getGlobalColourMapSize() const { return mGlobalColourMapSize; }
+		/// Get access to the global colour map, if enabled
+		const TexturePtr& getGlobalColourMap() const { return mColourMap; }
+
+		/** Widen a rectangular area of terrain to take into account an extrusion vector.
+		@param vec A vector in world space
+		@param inRect Input rectangle
+		@param inRect Output rectangle
+		*/
+		void widenRectByVector(const Vector3& vec, const Rect& inRect, Rect& outRect);
+
+		/** Widen a rectangular area of terrain to take into account an extrusion vector, 
+			but specify the min / max heights to extrude manually.
+		@param vec A vector in world space
+		@param inRect Input rectangle
+		@param minHeight, maxHeight The extents of the height to extrude
+		@param inRect Output rectangle
+		*/
+		void widenRectByVector(const Vector3& vec, const Rect& inRect, 
+			Real minHeight, Real maxHeight, Rect& outRect);
+
+		/** Free as many resources as possible for optimal run-time memory use.
+		@remarks
+			This class keeps some temporary storage around in order to make
+			certain actions (such as editing) possible more quickly. Calling this
+			method will cause as many of those resources as possible to be
+			freed. You might want to do this for example when you are finished
+			editing a particular terrain and want to have optimal runtime
+			efficiency.
+		*/
+		void freeTemporaryResources();
+
+		/** Get a blend texture with a given index.
+		@param index The blend texture index (note: not layer index; derive
+		the texture index from getLayerBlendTextureIndex)
+		*/
+		const TexturePtr& getLayerBlendTexture(uint8 index);
+
+		/** Get the texture index and colour channel of the blend information for 
+			a given layer. 
+		@param layerIndex The index of the layer (1 or higher, layer 0 has no blend data)
+		@return A pair in which the first value is the texture index, and the 
+			second value is the colour channel (RGBA)
+		*/
+		std::pair<uint8,uint8> getLayerBlendTextureIndex(uint8 layerIndex);
+
+		/** Request internal implementation options for the terrain material to use, 
+			in this case vertex morphing information. 
+		The TerrainMaterialGenerator should call this method to specify the 
+		options it would like to use when creating a material. Not all the data
+		is guaranteed to be up to date on return from this method - for example som
+		maps may be generated in the background. However, on return from this method
+		all the features that are requested will be referenceable by materials, the
+		data may just take a few frames to be fully populated.
+		@param morph Whether LOD morphing information is required to be calculated
+		*/
+		void _setMorphRequired(bool morph) { mLodMorphRequired = morph; }
+		/// Get whether LOD morphing is needed
+		bool _getMorphRequired() const { return mLodMorphRequired; }
+
+		/** Request internal implementation options for the terrain material to use, 
+		in this case a terrain-wide normal map. 
+		The TerrainMaterialGenerator should call this method to specify the 
+		options it would like to use when creating a material. Not all the data
+		is guaranteed to be up to date on return from this method - for example some
+		maps may be generated in the background. However, on return from this method
+		all the features that are requested will be referenceable by materials, the
+		data may just take a few frames to be fully populated.
+		@param normalMap Whether a terrain-wide normal map is requested. This is usually
+			mutually exclusive with the lightmap option.
+		*/
+		void _setNormalMapRequired(bool normalMap);
+
+		/** Request internal implementation options for the terrain material to use, 
+		in this case a terrain-wide normal map. 
+		The TerrainMaterialGenerator should call this method to specify the 
+		options it would like to use when creating a material. Not all the data
+		is guaranteed to be up to date on return from this method - for example some
+		maps may be generated in the background. However, on return from this method
+		all the features that are requested will be referenceable by materials, the
+		data may just take a few frames to be fully populated.
+		@param lightMap Whether a terrain-wide lightmap including precalculated 
+			lighting is required (light direction in TerrainGlobalOptions)
+		@param shadowsOnly If true, the lightmap contains only shadows, 
+			no directional lighting intensity
+		*/
+		void _setLightMapRequired(bool lightMap, bool shadowsOnly = false);
+
+		/** Request internal implementation options for the terrain material to use, 
+		in this case a terrain-wide composite map. 
+		The TerrainMaterialGenerator should call this method to specify the 
+		options it would like to use when creating a material. Not all the data
+		is guaranteed to be up to date on return from this method - for example some
+		maps may be generated in the background. However, on return from this method
+		all the features that are requested will be referenceable by materials, the
+		data may just take a few frames to be fully populated.
+		@param compositeMap Whether a terrain-wide composite map is needed. A composite
+		map is a texture with all of the blending and lighting baked in, such that
+		at distance this texture can be used as an approximation of the multi-layer
+		blended material. It is actually up to the material generator to render this
+		composite map, because obviously precisely what it looks like depends on what
+		the main material looks like. For this reason, the composite map is one piece
+		of derived terrain data that is always calculated in the render thread, and
+		usually on the GPU. It is expected that if this option is requested, 
+		the material generator will use it to construct distant LOD techniques.
+		*/
+		void _setCompositeMapRequired(bool compositeMap);
+
+		/// Whether we're using vertex compression or not
+		bool _getUseVertexCompression() const; 
+		
+		/// WorkQueue::RequestHandler override
+		bool canHandleRequest(const WorkQueue::Request* req, const WorkQueue* srcQ);
+		/// WorkQueue::RequestHandler override
+		WorkQueue::Response* handleRequest(const WorkQueue::Request* req, const WorkQueue* srcQ);
+		/// WorkQueue::ResponseHandler override
+		bool canHandleResponse(const WorkQueue::Response* res, const WorkQueue* srcQ);
+		/// WorkQueue::ResponseHandler override
+		void handleResponse(const WorkQueue::Response* res, const WorkQueue* srcQ);
+
+		static const uint16 WORKQUEUE_DERIVED_DATA_REQUEST;
+
+
+		/// Utility method, get the first LOD Level at which this vertex is no longer included
+		uint16 getLODLevelWhenVertexEliminated(long x, long y);
+		/// Utility method, get the first LOD Level at which this vertex is no longer included
+		uint16 getLODLevelWhenVertexEliminated(long rowOrColulmn);
+
+
+		/// Get the top level of the quad tree which is used to divide up the terrain
+		TerrainQuadTreeNode* getQuadTree() { return mQuadTree; }
+
+		/// Get the (global) normal map texture
+		TexturePtr getTerrainNormalMap() const { return mTerrainNormalMap; }
+
+		/** Retrieve the terrain's neighbour, or null if not present.
+		@remarks
+			Terrains only know about their neighbours if they are notified via
+			setNeighbour. This information is not saved with the terrain since every
+			tile must be able to be independent.
+		@param index The index of the neighbour
+		*/
+		Terrain* getNeighbour(NeighbourIndex index);
+
+		/** Set a terrain's neighbour, or null to detach one. 
+		@remarks
+			This information is not saved with the terrain since every
+			tile must be able to be independent. However if modifications are
+			made to a tile which can affect its neighbours, while connected the
+			changes will be propagated. 
+		@param index The index of the neighbour
+		@param neighbour The terrain instance to become the neighbour, or null to reset.
+		@param recalculate If true, this terrain instance will recalculate elements
+			that could be affected by the connection of this tile (e.g. matching 
+			heights, calcaulting normals, calculating shadows crossing the boundary). 
+			If false, this terrain's state is assumed to be up to date already 
+			(e.g. was calculated with this tile present before and the state saved). 
+		@param notifyOther Whether the neighbour should also be notified (recommended
+			to leave this at the default so relationships are up to date before
+			background updates are triggered)
+		*/
+		void setNeighbour(NeighbourIndex index, Terrain* neighbour, bool recalculate = false, bool notifyOther = true);
+
+		/** Get the opposite neighbour relationship (useful for finding the 
+			neighbour index from the perspective of the tile the other side of the
+			boundary).
+		*/
+		static NeighbourIndex getOppositeNeighbour(NeighbourIndex index);
+
+		/** Get the neighbour enum for a given offset in a grid (signed).
+		*/
+		static NeighbourIndex getNeighbourIndex(long offsetx, long offsety);
+
+		/** Tell this instance to notify all neighbours that will be affected
+			by a height change that has taken place. 
+		@remarks
+			This method will determine which neighbours need notification and call
+			their neighbourModified method. It is called automatically by 
+			updateGeometry().
+		*/
+		void notifyNeighbours();
+
+		/** Notify that a neighbour has just finished updating and that this
+			change affects this tile. 
+		@param index The neighbour index (from this tile's perspective)
+		@param edgerect The area at the edge of this tile that needs height / normal
+			recalculation (may be null)
+		@param shadowrect The area on this tile where shadows need recalculating (may be null)
+		*/
+		void neighbourModified(NeighbourIndex index, const Rect& edgerect, const Rect& shadowrect);
+
+		/** Utility method to pick a neighbour based on a ray. 
+		@param ray The ray in world space
+		@param distanceLimit Limit beyond which we want to ignore neighbours (0 for infinite)
+		@return The first neighbour along this ray, or null
+		*/
+		Terrain* raySelectNeighbour(const Ray& ray, Real distanceLimit = 0);
+
+		/** Dump textures to files.
+		@remarks
+			This is a debugging method.
+		*/
+		void _dumpTextures(const String& prefix, const String& suffix);
+
+		/** Query whether a derived data update is in progress or not. */
+		bool isDerivedDataUpdateInProgress() const { return mDerivedDataUpdateInProgress; }
+
+
+		/// Utility method to convert axes from world space to terrain space (xy terrain, z up)
+		static void convertWorldToTerrainAxes(Alignment align, const Vector3& worldVec, Vector3* terrainVec);
+		/// Utility method to convert axes from terrain space (xy terrain, z up) tp world space
+		static void convertTerrainToWorldAxes(Alignment align, const Vector3& terrainVec, Vector3* worldVec);
+
+		/// Utility method to write a layer declaration to a stream
+		static void writeLayerDeclaration(const TerrainLayerDeclaration& decl, StreamSerialiser& ser);
+		/// Utility method to read a layer declaration from a stream
+		static bool readLayerDeclaration(StreamSerialiser& ser, TerrainLayerDeclaration& targetdecl);
+		/// Utility method to write a layer instance list to a stream
+		static void writeLayerInstanceList(const Terrain::LayerInstanceList& lst, StreamSerialiser& ser);
+		/// Utility method to read a layer instance list from a stream
+		static bool readLayerInstanceList(StreamSerialiser& ser, size_t numSamplers, Terrain::LayerInstanceList& targetlst);
+	protected:
+
+		void freeCPUResources();
+		void freeGPUResources();
+		void determineLodLevels();
+		void distributeVertexData();
+		void updateBaseScale();
+		void createGPUBlendTextures();
+		void createLayerBlendMaps();
+		void createOrDestroyGPUNormalMap();
+		void createOrDestroyGPUColourMap();
+		void createOrDestroyGPULightmap();
+		void createOrDestroyGPUCompositeMap();
+		void waitForDerivedProcesses();
+		void convertSpace(Space inSpace, const Vector3& inVec, Space outSpace, Vector3& outVec, bool translation) const;
+		Vector3 convertWorldToTerrainAxes(const Vector3& inVec) const;
+		Vector3 convertTerrainToWorldAxes(const Vector3& inVec) const;
+		/** Get a Vector3 of the world-space point on the terrain, aligned Y-up always.
+		@note This point is relative to Terrain::getPosition
+		*/
+		void getPointAlign(long x, long y, Alignment align, Vector3* outpos);
+		/** Get a Vector3 of the world-space point on the terrain, supplying the
+		height data manually (can be more optimal). 
+		@note This point is relative to Terrain::getPosition
+		*/
+		void getPointAlign(long x, long y, float height, Alignment align, Vector3* outpos);
+		void calculateCurrentLod(Viewport* vp);
+		/// Test a single quad of the terrain for ray intersection.
+		std::pair<bool, Vector3> checkQuadIntersection(int x, int y, const Ray& ray); //const;
+
+        /// Delete blend maps for all layers >= lowIndex
+        void deleteBlendMaps(uint8 lowIndex);
+        /// Shift/slide all GPU blend texture channels > index up one slot.  Blend data may shift into the next texture
+        void shiftUpGPUBlendChannels(uint8 index);
+        /// Shift/slide all GPU blend texture channels > index down one slot.  Blend data may shift into the previous texture
+        void shiftDownGPUBlendChannels(uint8 index);
+        /// Copy a GPU blend channel from one source to another.  Source and Dest are not required to be in the same texture
+        void copyBlendTextureChannel(uint8 srcIndex, uint8 srcChannel, uint8 destIndex, uint8 destChannel );
+        /// Reset a blend channel back to full black
+	    void clearGPUBlendChannel(uint8 index, uint channel);
+
+		void copyGlobalOptions();
+		void checkLayers(bool includeGPUResources);
+		void checkDeclaration();
+		void deriveUVMultipliers();
+		PixelFormat getBlendTextureFormat(uint8 textureIndex, uint8 numLayers);
+
+		void updateDerivedDataImpl(const Rect& rect, const Rect& lightmapExtraRect, bool synchronous, uint8 typeMask);
+
+		void getEdgeRect(NeighbourIndex index, long range, Rect* outRect);
+		// get the equivalent of the passed in edge rectangle in neighbour
+		void getNeighbourEdgeRect(NeighbourIndex index, const Rect& inRect, Rect* outRect);
+		// get the equivalent of the passed in edge point in neighbour
+		void getNeighbourPoint(NeighbourIndex index, long x, long y, long *outx, long *outy);
+		// overflow a point into a neighbour index and point
+		void getNeighbourPointOverflow(long x, long y, NeighbourIndex *outindex, long *outx, long *outy);
+
+		
+
+		uint16 mWorkQueueChannel;
+		SceneManager* mSceneMgr;
+		SceneNode* mRootNode;
+		String mResourceGroup;
+		bool mIsLoaded;
+		bool mModified;
+		bool mHeightDataModified;
+		
+		/// The height data (world coords relative to mPos)
+		float* mHeightData;
+		/// The delta information defining how a vertex moves before it is removed at a lower LOD
+		float* mDeltaData;
+		Alignment mAlign;
+		Real mWorldSize;
+		uint16 mSize;
+		uint16 mMaxBatchSize;
+		uint16 mMinBatchSize;
+		Vector3 mPos;
+		TerrainQuadTreeNode* mQuadTree;
+		uint16 mNumLodLevels;
+		uint16 mNumLodLevelsPerLeafNode;
+		uint16 mTreeDepth;
+		/// Base position in world space, relative to mPos
+		Real mBase;
+		/// Relationship between one point on the terrain and world size
+		Real mScale;
+		TerrainLayerDeclaration mLayerDecl;
+		LayerInstanceList mLayers;
+		RealVector mLayerUVMultiplier;
+
+		Real mSkirtSize;
+		uint8 mRenderQueueGroup;
+		uint32 mVisibilityFlags;
+		uint32 mQueryFlags;
+
+		Rect mDirtyGeometryRect;
+		Rect mDirtyDerivedDataRect;
+		Rect mDirtyGeometryRectForNeighbours;
+		Rect mDirtyLightmapFromNeighboursRect;
+		bool mDerivedDataUpdateInProgress;
+		uint8 mDerivedUpdatePendingMask; // if another update is requested while one is already running
+
+		/// A data holder for communicating with the background derived data update
+		struct DerivedDataRequest
+		{
+			Terrain* terrain;
+			// types requested
+			uint8 typeMask;
+			Rect dirtyRect;
+			Rect lightmapExtraDirtyRect;
+			_OgreTerrainExport friend std::ostream& operator<<(std::ostream& o, const DerivedDataRequest& r)
+			{ return o; }		
+		};
+
+		/// A data holder for communicating with the background derived data update
+		struct DerivedDataResponse
+		{
+			Terrain* terrain;
+			// remaining types not yet processed
+			uint8 remainingTypeMask;
+			// The area of deltas that was updated
+			Rect deltaUpdateRect;
+			// the area of normals that was updated
+			Rect normalUpdateRect;
+			// the area of lightmap that was updated
+			Rect lightmapUpdateRect;
+			// all CPU-side data, independent of textures; to be blitted in main thread
+			PixelBox* normalMapBox;
+			PixelBox* lightMapBox;
+			_OgreTerrainExport friend std::ostream& operator<<(std::ostream& o, const DerivedDataResponse& r)
+			{ return o; }		
+		};
+
+		String mMaterialName;
+		mutable MaterialPtr mMaterial;
+		mutable TerrainMaterialGeneratorPtr mMaterialGenerator;
+		mutable unsigned long long int mMaterialGenerationCount;
+		mutable bool mMaterialDirty;
+		mutable bool mMaterialParamsDirty;
+
+		uint16 mLayerBlendMapSize;
+		uint16 mLayerBlendMapSizeActual;
+		typedef vector<uint8*>::type BytePointerList;
+		/// Staging post for blend map data
+		BytePointerList mCpuBlendMapStorage;
+		typedef vector<TexturePtr>::type TexturePtrList;
+		TexturePtrList mBlendTextureList;
+		TerrainLayerBlendMapList mLayerBlendMapList;
+
+		uint16 mGlobalColourMapSize;
+		bool mGlobalColourMapEnabled;
+		TexturePtr mColourMap;
+		uint8* mCpuColourMapStorage;
+
+		uint16 mLightmapSize;
+		uint16 mLightmapSizeActual;
+		TexturePtr mLightmap;
+		uint8* mCpuLightmapStorage;
+
+		uint16 mCompositeMapSize;
+		uint16 mCompositeMapSizeActual;
+		TexturePtr mCompositeMap;
+		uint8* mCpuCompositeMapStorage;
+		Rect mCompositeMapDirtyRect;
+		unsigned long mCompositeMapUpdateCountdown;
+		unsigned long mLastMillis;
+		/// true if the updates included lightmap changes (widen)
+		bool mCompositeMapDirtyRectLightmapUpdate;
+		mutable MaterialPtr mCompositeMapMaterial;
+
+
+		static NameGenerator msBlendTextureGenerator;
+		static NameGenerator msNormalMapNameGenerator;
+		static NameGenerator msLightmapNameGenerator;
+		static NameGenerator msCompositeMapNameGenerator;
+
+		bool mLodMorphRequired;
+		bool mNormalMapRequired;
+		bool mLightMapRequired;
+		bool mLightMapShadowsOnly;
+		bool mCompositeMapRequired;
+		/// Texture storing normals for the whole terrrain
+		TexturePtr mTerrainNormalMap;
+
+		/// Pending data 
+		PixelBox* mCpuTerrainNormalMap;
+
+		const Camera* mLastLODCamera;
+		unsigned long mLastLODFrame;
+		int mLastViewportHeight;
+
+		Terrain* mNeighbours[NEIGHBOUR_COUNT];
+
+		GpuBufferAllocator* mCustomGpuBufferAllocator;
+		DefaultGpuBufferAllocator mDefaultGpuBufferAllocator;
+
+		size_t getPositionBufVertexSize() const;
+		size_t getDeltaBufVertexSize() const;
+
+	};
+
+
+	/** Options class which just stores default options for the terrain.
+	@remarks
+		None of these options are stored with the terrain when saved. They are
+		options that you can use to modify the behaviour of the terrain when it
+		is loaded or created. 
+	@note
+		You should construct a single instance of this class per application and
+		do so before you start working with any other terrain classes.
+	*/
+	class _OgreTerrainExport TerrainGlobalOptions : public TerrainAlloc, public Singleton<TerrainGlobalOptions>
+	{
+	protected:
+
+		Real mSkirtSize;
+		Vector3 mLightMapDir;
+		bool mCastsShadows;
+		Real mMaxPixelError;
+		uint8 mRenderQueueGroup;
+		uint32 mVisibilityFlags;
+		uint32 mQueryFlags;
+		bool mUseRayBoxDistanceCalculation;
+		TerrainMaterialGeneratorPtr mDefaultMaterialGenerator;
+		uint16 mLayerBlendMapSize;
+		Real mDefaultLayerTextureWorldSize;
+		uint16 mDefaultGlobalColourMapSize;
+		uint16 mLightmapSize;
+		uint16 mCompositeMapSize;
+		ColourValue mCompositeMapAmbient;
+		ColourValue mCompositeMapDiffuse;
+		Real mCompositeMapDistance;
+		String mResourceGroup;
+		bool mUseVertexCompressionWhenAvailable;
+
+	public:
+		TerrainGlobalOptions();
+		virtual ~TerrainGlobalOptions() {}
+
+
+		/** The default size of 'skirts' used to hide terrain cracks
+		(default 10)
+		*/
+		Real getSkirtSize() { return mSkirtSize; }
+		/** method - the default size of 'skirts' used to hide terrain cracks
+		(default 10)
+		@remarks
+			Changing this value only applies to Terrain instances loaded / reloaded afterwards.
+		*/
+		void setSkirtSize(Real skirtSz) { mSkirtSize = skirtSz; }
+		/// Get the shadow map light direction to use (world space)
+		const Vector3& getLightMapDirection() { return mLightMapDir; }
+		/** Set the shadow map light direction to use (world space). */
+		void setLightMapDirection(const Vector3& v) { mLightMapDir = v; }
+		/// Get the composite map ambient light to use 
+		const ColourValue& getCompositeMapAmbient() { return mCompositeMapAmbient; }
+		/// Set the composite map ambient light to use 
+		void setCompositeMapAmbient(const ColourValue& c) { mCompositeMapAmbient = c; }
+		/// Get the composite map iffuse light to use 
+		const ColourValue& getCompositeMapDiffuse() { return mCompositeMapDiffuse; }
+		/// Set the composite map diffuse light to use 
+		void setCompositeMapDiffuse(const ColourValue& c) { mCompositeMapDiffuse = c; }
+		/// Get the distance at which to start using a composite map if present
+		Real getCompositeMapDistance() { return mCompositeMapDistance; }
+		/// Set the distance at which to start using a composite map if present
+		void setCompositeMapDistance(Real c) { mCompositeMapDistance = c; }
+
+
+		/** Whether the terrain will be able to cast shadows (texture shadows
+		only are supported, and you must be using depth shadow maps).
+		*/
+		bool getCastsDynamicShadows() { return mCastsShadows; }
+
+		/** Whether the terrain will be able to cast shadows (texture shadows
+		only are supported, and you must be using depth shadow maps).
+		This value can be set dynamically, and affects all existing terrains.
+		It defaults to false. 
+		*/
+		void setCastsDynamicShadows(bool s) { mCastsShadows = s; }
+
+		/** Get the maximum screen pixel error that should be allowed when rendering. */
+		Real getMaxPixelError() { return mMaxPixelError; }
+
+		/** Set the maximum screen pixel error that should  be allowed when rendering. 
+		@note
+			This value can be varied dynamically and affects all existing terrains.
+			It will be weighted by the LOD bias on viewports. 
+		*/
+		void setMaxPixelError(Real pixerr) { mMaxPixelError = pixerr; }
+
+		/// Get the render queue group that this terrain will be rendered into
+		uint8 getRenderQueueGroup(void) { return mRenderQueueGroup; }
+		/** Set the render queue group that terrains will be rendered into.
+		@remarks This applies to newly created terrains, after which they will
+			maintain their own queue group settings
+		*/
+		void setRenderQueueGroup(uint8 grp) { mRenderQueueGroup = grp; }
+
+		/// Get the visbility flags that terrains will be rendered with
+		uint32 getVisibilityFlags(void) { return mVisibilityFlags; }
+		/** Set the visbility flags that terrains will be rendered with
+		@remarks This applies to newly created terrains, after which they will
+		maintain their own settings
+		*/
+		void setVisibilityFlags(uint32 flags) { mVisibilityFlags = flags; }
+
+		/** Set the default query flags for terrains.
+		@remarks This applies to newly created terrains, after which they will
+		maintain their own settings
+		*/
+		void  setQueryFlags(uint32 flags) { mQueryFlags = flags; }
+		/** Get the default query flags for terrains.
+		*/
+		uint32 getQueryFlags(void) { return mQueryFlags; }
+
+		/** As setQueryFlags, except the flags passed as parameters are appended to the existing flags on this object. */
+		void addQueryFlags(uint32 flags) { mQueryFlags |= flags; }
+
+		/* As setQueryFlags, except the flags passed as parameters are removed from the existing flags on this object. */
+		void removeQueryFlags(uint32 flags) { mQueryFlags &= ~flags; }
+
+		/** Returns whether or not to use an accurate calculation of camera distance
+			from a terrain tile (ray / AABB intersection) or whether to use the
+			simpler distance from the tile centre. 
+		*/
+		bool getUseRayBoxDistanceCalculation() { return mUseRayBoxDistanceCalculation; }
+
+		/** Sets whether to use an accurate ray / box intersection to determine
+			distance from a terrain tile, or whether to use the simple distance
+			from the tile centre.
+			Using ray/box intersection will result in higher detail terrain because 
+			the LOD calculation is more conservative, assuming the 'worst case scenario' 
+			of a large height difference at the edge of a tile. This is guaranteed to give you at least
+			the max pixel error or better, but will often give you more detail than
+			you need. Not using the ray/box method is cheaper but will only use
+			the max pixel error as a guide, the actual error will vary above and
+			below that. The default is not to use the ray/box approach.
+		*/
+		void setUseRayBoxDistanceCalculation(bool rb) { mUseRayBoxDistanceCalculation = rb; }
+
+		/** Get the default material generator.
+		*/
+		TerrainMaterialGeneratorPtr getDefaultMaterialGenerator();
+
+		/** Set the default material generator.
+		*/
+		void setDefaultMaterialGenerator(TerrainMaterialGeneratorPtr gen);
+
+		/** Get the default size of the blend maps for a new terrain. 
+		*/
+		uint16 getLayerBlendMapSize() { return mLayerBlendMapSize; }
+
+		/** Sets the default size of blend maps for a new terrain.
+		This is the resolution of each blending layer for a new terrain. 
+		Once created, this information will be stored with the terrain. 
+		*/
+		void setLayerBlendMapSize(uint16 sz) { mLayerBlendMapSize = sz;}
+
+		/** Get the default world size for a layer 'splat' texture to cover. 
+		*/
+		Real getDefaultLayerTextureWorldSize() { return mDefaultLayerTextureWorldSize; }
+
+		/** Set the default world size for a layer 'splat' texture to cover. 
+		*/
+		void setDefaultLayerTextureWorldSize(Real sz) { mDefaultLayerTextureWorldSize = sz; }
+
+		/** Get the default size of the terrain global colour map for a new terrain. 
+		*/
+		uint16 getDefaultGlobalColourMapSize() { return mDefaultGlobalColourMapSize; }
+
+		/** Set the default size of the terrain global colour map for a new terrain. 
+		Once created, this information will be stored with the terrain. 
+		*/
+		void setDefaultGlobalColourMapSize(uint16 sz) { mDefaultGlobalColourMapSize = sz;}
+
+
+		/** Get the default size of the lightmaps for a new terrain. 
+		*/
+		uint16 getLightMapSize() { return mLightmapSize; }
+
+		/** Sets the default size of lightmaps for a new terrain.
+		*/
+		void setLightMapSize(uint16 sz) { mLightmapSize = sz;}
+
+		/** Get the default size of the composite maps for a new terrain. 
+		*/
+		uint16 getCompositeMapSize() { return mCompositeMapSize; }
+
+		/** Sets the default size of composite maps for a new terrain.
+		*/
+		void setCompositeMapSize(uint16 sz) { mCompositeMapSize = sz;}
+
+		/** Set the default resource group to use to load / save terrains.
+		*/
+		void setDefaultResourceGroup(const String& grp) { mResourceGroup = grp; }
+
+		/** Get the default resource group to use to load / save terrains.
+		*/
+		const String& getDefaultResourceGroup() { return mResourceGroup; }
+		
+		/** Get whether to allow vertex compression to be used when the material
+			generator states that it supports it.
+		*/
+		bool getUseVertexCompressionWhenAvailable() const { return mUseVertexCompressionWhenAvailable; }
+
+		/** Set whether to allow vertex compression to be used when the material
+		 generator states that it supports it.
+		 @note You should only call this before creating any terrain instances. 
+		 The default is true, so if a material generator supports compressed vertices, 
+		 and so does the hardware (this basically means shader support), they will be used).
+		 However you can disable this in an emergency if required.
+		 */
+		void setUseVertexCompressionWhenAvailable(bool enable) { mUseVertexCompressionWhenAvailable = enable; }
+
+		/** Override standard Singleton retrieval.
+		@remarks
+		Why do we do this? Well, it's because the Singleton
+		implementation is in a .h file, which means it gets compiled
+		into anybody who includes it. This is needed for the
+		Singleton template to work, but we actually only want it
+		compiled into the implementation of the class based on the
+		Singleton, not all of them. If we don't change this, we get
+		link errors when trying to use the Singleton-based class from
+		an outside dll.
+		@par
+		This method just delegates to the template version anyway,
+		but the implementation stays in this single compilation unit,
+		preventing link errors.
+		*/
+		static TerrainGlobalOptions& getSingleton(void);
+		/** Override standard Singleton retrieval.
+		@remarks
+		Why do we do this? Well, it's because the Singleton
+		implementation is in a .h file, which means it gets compiled
+		into anybody who includes it. This is needed for the
+		Singleton template to work, but we actually only want it
+		compiled into the implementation of the class based on the
+		Singleton, not all of them. If we don't change this, we get
+		link errors when trying to use the Singleton-based class from
+		an outside dll.
+		@par
+		This method just delegates to the template version anyway,
+		but the implementation stays in this single compilation unit,
+		preventing link errors.
+		*/
+		static TerrainGlobalOptions* getSingletonPtr(void);
+
+
+	};
+
+
+	/** @} */
+	/** @} */
+}
+
+
+
+
+#endif