/****************************************************************************************************

		I3DShTerrainFilter.h
		Copyright: (c) 2001 Eovia Corp. All rights reserved.

		Terrain filter shell definition

		Author:	Pierre-Sylvain
		Date:	10/21/2003

****************************************************************************************************/

#ifndef __I3DShTerrainFilter__
#define __I3DShTerrainFilter__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "APITypes.h"
#include "Index.h"
#include "MCCompObj.h"

//****** Globally Unique Ids *************************************************

MCDEFINE_GUID(IID_I3DShTerrainFilter, 0xf9f6d8ae, 0x656e, 0x4c92, 0xaa, 0xc0, 0x3c, 0x9b, 0x52, 0x26, 0x99, 0xb8);


//****************************************************************************

/// \addtogroup ShellInterface
/// \{

/// A terrain filter takes a height field as input and output another height field.
///
/// <P>There are two interfaces to access a terrain filter: The shell interface (I3DShTerrainFilter) and
/// the external interface (I3DExTerrainFilter) . You can get one from the other using QueryInterface.</P>
///
/// <P>Whenever it is possible you should use the Shell interface (I3DShTerrainFilter) to access the component
/// because the Shell will make sure that the parameter map of the external component is valid.
/// This is especially important if the component is animated. For more information on components
/// see the Overview of the SDK.</P>
/// 
/// \see I3DExTerrainFilter
///
struct I3DShTerrainFilter : public IMCUnknown
{
	// ****************************************************************************
	//								Shuffle
	// 
	/// Should change the seed of the random generator used by this filter (if the
	/// filter has a random component).
	/// 
	virtual void MCCOMAPI Shuffle() = 0;

	// ****************************************************************************
	//								Filter
	//
	/// Filter the height field. This is where the real work is done.
	///
	/// \param heightField	Array of real that defines the height field.
	/// \param heightBound	Height min and max of the terrain (must be updated
	///						by this function if the height bounds changed)
	/// \param size			size of the array
	/// \param cellSize		size of a cell of the grid
	///
	virtual void MCCOMAPI Filter(TMCArray<real>& heightField, TVector2& heightBound,
								 const TIndex2& size, const TVector2& cellSize) = 0;

	// ****************************************************************************
	//								CanBuildPreview
	//
	///	Returns true if the filter is able to make a preview
	///	of the final map working on a smaller map
	///
	virtual boolean MCCOMAPI CanBuildPreview() = 0;

	// ****************************************************************************
	//								SetTerrain
	// 
	/// Sets the terrain on which the filter is applied
	/// 
	/// \param terrainPrimitive  A pointer to the terrain primitive.
	/// 
	virtual void MCCOMAPI SetTerrain(I3DShPrimitiveComponent* terrainPrimitive)=0;

	// ****************************************************************************
	//								GetTerrain
	// 
	/// Returns the terrain primitive on which the filter is applied
	/// 
	/// 
	virtual I3DShPrimitiveComponent* MCCOMAPI GetTerrain()=0;

};

/// \}

#endif
