/*

-----------------------------------------------------------------------------

This source file is part of OGRE

(Object-oriented Graphics Rendering Engine)

For the latest info, see http://www.ogre3d.org/

Copyright (c) 2000-2014 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 "OgreVector.h"

#include "OgreAxisAlignedBox.h"

#include "OgreSceneManager.h"

#include "OgreTerrainMaterialGenerator.h"

#include "OgreTerrainLayerBlendMap.h"

#include "OgreWorkQueue.h"

#include "OgreTerrainLodManager.h"

#include <future>

namespace Ogre

{

    /** \addtogroup Optional

    *  @{

    */

    /** \defgroup Terrain Terrain

    *   Editable %Terrain System with LOD @cite de2000fast, serialization and \ref Paging support

    *  @{

    */

    /** 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 RGBA</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:

        friend class TerrainLodManager;

        /** 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 uint32 TERRAINGENERALINFO_CHUNK_ID;

        static const uint16 TERRAINGENERALINFO_CHUNK_VERSION;

        static const uint32 LOD_MORPH_CUSTOM_PARAM;

        typedef std::vector<Real> 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 std::vector<LayerInstance> 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

                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.

            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.

                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. 

                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 forTerrain

            @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.

                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();

            virtual ~DefaultGpuBufferAllocator();

            void allocateVertexBuffers(Terrain* forTerrain, size_t numVertices, HardwareVertexBufferSharedPtr& destPos, HardwareVertexBufferSharedPtr& destDelta) override;

            void freeVertexBuffers(const HardwareVertexBufferSharedPtr& posbuf, const HardwareVertexBufferSharedPtr& deltabuf) override;

            HardwareIndexBufferSharedPtr getSharedIndexBuffer(uint16 batchSize, 

                uint16 vdatasize, size_t vertexIncrement, uint16 xoffset, uint16 yoffset, uint16 numSkirtRowsCols, 

                uint16 skirtRowColSkip) override;

            void freeAllBuffers() override;

            /** '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);

        private:

            typedef std::list<HardwareVertexBufferSharedPtr> VBufList;

            VBufList mFreePosBufList;

            VBufList mFreeDeltaBufList;

            typedef std::map<uint32, HardwareIndexBufferSharedPtr> 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. 

            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, uint16 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.

            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.

            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(DataStreamPtr& stream);

        /** Prepare terrain data from saved data.

            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. 

            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. 

            This method must be called in the main render thread. 

        @param lodLevel Load the specified LOD level

        @param synchronous Load type

        */

        void load(int lodLevel = 0, bool synchronous = true);

        /** Return whether the terrain is loaded. 

            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. 

            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. 

        This flag is reset on save().

        */

        bool isHeightDataModified() const { return mHeightDataModified; }

        /** Unload the terrain and free GPU resources. 

            This method must be called in the main render thread.

        */

        void unload();

        /** Free CPU resources created during prepare methods.

            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.

            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(uint32 x, uint32 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(uint32 x, uint32 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(uint32 x, uint32 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) const;

        /** 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) const;

        /// @overload

        float getHeightAtWorldPosition(const Vector3& pos) const;

        /** Get a pointer to all the delta data for this terrain.

            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() const;

        /** Get a pointer to the delta data for a given point. 

        */

        const float* getDeltaData(uint32 x, uint32 y) const;

        /** 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(uint32 x, uint32 y, Vector3* outpos) const;

        /** 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(int32 x, int32 y, Vector3* outpos) const;

        /** 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(uint32 x, uint32 y, float height, Vector3* outpos) const;

        /** Get a transform which converts Vector4(xindex, yindex, height, 1) into 

            an object-space position including scalings and alignment.

        */

        Affine3 getPointTransform() 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

        @param[out] outVec

        */

        void getTerrainVector(const Vector3& inVec, Vector3* outVec) const;

        /// @overload

        void getTerrainVector(Real x, Real y, Real z, Vector3* outVec) const;

        /** 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

        @param[out] outVec

        @param align The alignment of the terrain

        */

        void getTerrainVectorAlign(const Vector3& inVec, Alignment align, Vector3* outVec) const;

        /// @overload

        void getTerrainVectorAlign(Real x, Real y, Real z, Alignment align, Vector3* outVec) const;

        /** 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

        @param[out] outVec

        */

        void getVector(const Vector3& inVec, Vector3* outVec) const;

        /// @overload

        void getVector(Real x, Real y, Real z, Vector3* outVec) const;

        /** 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

        @param[out] outVec

        @param align The alignment of the terrain

        */

        void getVectorAlign(const Vector3& inVec, Alignment align, Vector3* outVec) const;

        /// @overload

        void getVectorAlign(Real x, Real y, Real z, Alignment align, Vector3* outVec) const;

        /** 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) const;

        /// @overload

        void getPosition(Real x, Real y, Real z, Vector3* outWSpos) const;

        /** 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) const;

        /// @overload

        void getTerrainPosition(Real x, Real y, Real z, Vector3* outTSpos) const;

        /** 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). 

        @param align The alignment of the terrain

        */

        void getPositionAlign(const Vector3& TSpos, Alignment align, Vector3* outWSpos) const;

        /// @overload

        void getPositionAlign(Real x, Real y, Real z, Alignment align, Vector3* outWSpos) const;

        /** 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.

        @param align The alignment of the terrain

        */

        void getTerrainPositionAlign(const Vector3& WSpos, Alignment align, Vector3* outTSpos) const;

        /// @overload

        void getTerrainPositionAlign(Real x, Real y, Real z, Alignment align, Vector3* outTSpos) const;

        /// 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);

        /// @name Layers

        /// @{

        /** 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. 

            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 layerIndex The layer index.

        @param samplerIndex The sampler index within a layer

        @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. 

            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.

            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.