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

		IShRasterLayerUtilities.h

		Copyright: (c) 2001 Eovia Corp. All rights reserved.
	
		Author:	Christy
		Date:	11/18/98

		Revision History

		when		who			what & why
		==========	==========	======================================================
		12/06/99	Nba			added keep tiles in memory for resized layer
		03/16/99	dsm			resized layer from chunky or planar layer, or from single channel
		03/09/99	dsm			resized channel for display
		01/12/99	dsm			added CreateResizedLayer
		12/18/98	Nba			replaced IXX *& by IXX **
		12/04/98	dsm			added AddNewChannel

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

#ifndef __IShRasterLayerUtilities__
#define __IShRasterLayerUtilities__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ComTypes.h"
#include "IShChannel.h"
#include "ImageAPITypes.h"

struct APIDocumentHandle;
struct IShRasterLayer;
struct IMCFile;
struct TGBuffer32List;
struct IShLayerList;
struct IYeildCallBackFunc;

// Opaque references to the temp file and tile pool used by a raster layer.
// Many raster files can be created with the same temp file or tile pool.
struct MCRasterLayerTempFileHandle;
struct MCRasterLayerTilePoolHandle;
struct TPSOptions;

class  TMCString;

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

MCDEFINE_GUID_H(IID_IShRasterLayerUtilities);

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

/// methods for layer resizing (faster to better order)
///
enum EResizeMethod
{	
	eResizeMethodSample1,	///< one pixel dst = one pixel src
	eResizeMethodSample4,	///< one pixel dst = sum(four pixels src) / 4
	eResizeMethodLinear,	///< one pixel dst = average color on a real rect in src
	eResizeMethodBicubic	///< bicubical interpolation
};

// how to fill single channel resized layer
enum EResizedLayerFill
{
	eResizedLayerFillSingle,		///< single channel, not for display
	eResizedLayerFillDisplayGray,	///< single channel, converted into R, G and B
	eResizedLayerFillExtendBlack,	///< displays the R, G or B channel as is and fill others with black
	eResizedLayerFillExtendWhite	///< or white
};

    
/// \addtogroup Utilities
/// \{

/// IShRasterLayerUtilties allows to create a rasterlayer object
/// for storing large amounts of data with typed-channel support that is
/// spooled to disk. This is a single rasterlayer not connected to a
/// document or composition.
///
struct IShRasterLayerUtilities: public IMCUnknown
{
public:
	// ****************************************************************************
	//								CreateRasterLayer
	// 
	/// Creates a new image.
	/// 
	/// \param rasterLayer  the created image
	/// \param width        the width of the image
	/// \param height       the height of the image
	/// \param colorType    the colors channels of the image
	/// \param bitDepth     must be 8, 16 or 32
	/// \param fileHandle   can be null (Default one will be provided)
	/// \param poolHandle   can be null (Default one will be provided)
	/// 
	virtual MCCOMErr MCCOMAPI CreateRasterLayer						(	IShRasterLayer**				rasterLayer,
																		uint32							width,
																		uint32							height,
																		ELayerColorType					colorType,
																		uint32							bitDepth,
																		MCRasterLayerTempFileHandle*	fileHandle = nil,
																		MCRasterLayerTilePoolHandle*	poolHandle = nil)=0;
	
	// ****************************************************************************
	//								InitRasterLayer
	// 
	/// Initialize a raster layer.
	/// 
	/// \param rasterLayer  The rasterLayer to initialize.
	/// \param width        The new width of the rasterLayer
	/// \param height       The new height of the rasterLayer
	/// \param colorType    The type of channels contained in this raster layer (for ex eLayerRGB or eLayerRGBA)
	/// \param bitDepth    The bit depth (must be 8, 16 or 32)
	/// 
	virtual void MCCOMAPI InitRasterLayer(IShRasterLayer*	rasterLayer,
										  uint32							width,
										  uint32							height,
										  ELayerColorType					colorType,
										  uint32							bitDepth
										  ) = 0;
	virtual void MCCOMAPI InitRasterLayer(IShRasterLayer* rasterLayer, const TMCRect& bounds, ELayerColorType colorType, uint32 bitDepth) = 0;

	/// Undocumented (very rarely used)
	///
	virtual MCCOMErr MCCOMAPI CreateTempFile						(	MCRasterLayerTempFileHandle*&	out_handle)=0;

	/// Undocumented (very rarely used)
	///
	virtual MCCOMErr MCCOMAPI ReleaseTempFile						(	MCRasterLayerTempFileHandle*	handle)=0;

	/// Undocumented (very rarely used)
	///
	virtual MCCOMErr MCCOMAPI CreateTilePool						(	MCRasterLayerTilePoolHandle*&	out_handle)=0;

	/// Undocumented (very rarely used)
	///
	virtual MCCOMErr MCCOMAPI ReleaseTilePool						(	MCRasterLayerTilePoolHandle*	handle)=0;



	/// Adds a new channel to an existing image.
	///
	virtual MCCOMErr MCCOMAPI AddNewChannel							(	IShRasterLayer*		raster, 
																		const TChannelID&	id, 
																		const uint32		bitDepth, 
																		IShChannel**		channel) = 0;

	/// Not implemented, do NOT use
	///
	virtual MCCOMErr MCCOMAPI ResizeLayer							(	IShRasterLayer*		source, 
																		const TMCRect&		sourceRect, 
																		IShRasterLayer*		dest, 
																		const TMCRect&		destRect, 
																		const TChannelID*	channelIDs, 
																		uint32				nbChannels, 
																		EResizeMethod		method) = 0;

	/// Creates a new channel with a different size from the source channel
	///
	virtual MCCOMErr MCCOMAPI ResizeChannel							(	IShChannel*			source, 
																		const TMCRect&		sourceRect, 
																		IShChannel*			dest, 
																		const TMCRect&		destRect, 
																		EResizeMethod		method) = 0;


	/// Creates a new image with a different size from the source image
	///
	virtual MCCOMErr MCCOMAPI CreateResizedLayer					(	IShRasterLayer*		source, 
																		const TMCRect&		sourceRect, 
																		IShRasterLayer**	resizedLayer, 
																		const TMCRect&		resizedLayerSize, 
																		const TChannelID*	channelIDs, 
																		uint32				nbChannels, 
																		EResizeMethod		method, 
																		boolean				keepTilesInMemory) = 0;


	/// Undocumented
	///
	virtual MCCOMErr MCCOMAPI CreateResizedLayerFromSingleChannel	(	IShChannel*			source, 
																		const TMCRect&		sourceRect, 
																		IShRasterLayer**	resizedLayer, 
																		const TMCRect&		resizedLayerSize, 
																		EResizeMethod		method, 
																		EResizedLayerFill	filling, 
																		boolean				keepTilesInMemory) = 0;


	// ****************************************************************************
	//								CreateEmptyRasterLayer
	// 
	/// Creates an image without anything in it.
	/// 
	/// \param rasterLayer  the resulting empty image
	/// 
	virtual MCCOMErr MCCOMAPI CreateEmptyRasterLayer				(	IShRasterLayer**	rasterLayer) = 0;


	// ****************************************************************************
	//								CopyRasterLayer
	// 
	/// Copy a raster layer
	/// 
	virtual MCCOMErr MCCOMAPI CopyRasterLayer						(IShRasterLayer* source, IShRasterLayer** dest) = 0;


	// ****************************************************************************
	//								GetScratchPath
	// 
	/// Returns the path where temporary user data is stored.
	/// 
	/// \param scratchPath  the path of the temp folder
	/// 
	virtual MCCOMErr MCCOMAPI GetScratchPath						(	TMCString&			scratchPath) = 0;
	

	// ****************************************************************************
	//								LoadRasterLayer
	// 
	/// Load an image from a file into a rasterLayer.
	/// \note This function will throw an exception if the file cannot be read. It is important to catch it.
	/// 
	/// \param rasterLayer  a pointer to a rasterLayer where the image will be stored
	/// \param aFile        a pointer to the file where the image is stored
	/// \param format       the format of the file (can be found using IMCFile::GetMCFileType
	/// \param param        parameters used to load the image (see TPSIOParameter)
	/// 
	virtual MCCOMErr MCCOMAPI LoadRasterLayer						(	IShRasterLayer*		rasterLayer, 
																		IMCFile*			aFile, 
																		IDType				format, 
																		TPSIOParameter*		param = nil) = 0;

	// ****************************************************************************
	//								LoadLayerList
	// 
	/// Load an image from a file into a layer list.
	/// \note This function will throw an exception if the file cannot be read. It is important to catch it.
	/// 
	/// \param layerList    a pointer to a layerList where the image will be stored
	/// \param aFile        a pointer to the file where the image is stored
	/// \param format       the format of the file (can be found using IMCFile::GetMCFileType
	/// \param forceLoad	force loading as layer list even if all layer list options are not supported
	/// \param param        parameters used to load the image (see TPSIOParameter)
	/// 
	virtual MCCOMErr MCCOMAPI LoadLayerList							(	IShLayerList*		layerList, 
																		IMCFile*			aFile, 
																		IDType				format,
																		boolean				forceLoad,
																		TPSIOParameter*		param = nil) = 0;
	
	// ****************************************************************************
	//								SaveRasterLayer
	// 
	/// Saves an image onto the disk.
	/// 
	/// \param rasterLayer      the image to save
	/// \param gBuffers			Optional pointer to a list of GBuffers associated with the image.
	/// \param aFile            the file into which the image should be written
	/// \param format           the format of the file
	/// \param displayOptions   should a dialog with format specific options (like compression) be shown
	/// \param pluginOptions    useless
	/// \param param            useless
	///
	virtual MCCOMErr MCCOMAPI SaveRasterLayer						(	IShRasterLayer*			rasterLayer, 
																		const TGBuffer32List*	gBuffers,
																		IMCFile*				aFile, 
																		IDType					format, 
																		boolean					displayOptions = true,
																		TPSOptions*				pluginOptions = nil,
																		TPSIOParameter*			param = nil) = 0;

	// ****************************************************************************
	//								SaveLayerList
	// 
	/// Saves an image onto the disk.
	/// 
	/// \param layerList        the image to save
	/// \param gBuffers			Optional pointer to a list of GBuffers associated with the image.
	/// \param aFile            the file into which the image should be written
	/// \param format           the format of the file
	/// \param displayOptions   should a dialog with format specific options (like compression) be shown
	/// \param pluginOptions    useless
	/// \param param            useless
	///
	virtual MCCOMErr MCCOMAPI SaveLayerList							(	IShLayerList*			layerList, 
																		const TGBuffer32List*	gBuffers,
																		IMCFile*				aFile, 
																		IDType					format, 
																		boolean					displayOptions = true,
																		TPSOptions*				pluginOptions = nil,
																		TPSIOParameter*			param = nil) = 0;

	/// Undocumented
	///
	virtual MCCOMErr MCCOMAPI GetDocumentHandleFromRasterLayer		(	IShRasterLayer*		rasterLayer, 
																		APIDocumentHandle** outHandle) = 0;
	

	// ****************************************************************************
	//								ResizeChunkyLayerToPixelBucket
	// 
	/// Copy the content of the rasterLayer inside the offscreen and resize if necessary. 
	/// \note The layer must be a chunky layer.
	/// 
	/// \param rasterLayer  the source layer
	/// \param pixelBucket  the destination offscreen
    /// \param callBack     a yeild callback if needed
	/// 
	virtual void MCCOMAPI ResizeChunkyLayerToPixelBucket			(	IShRasterLayer*		rasterLayer,
																		TMCPixelBucket&		pixelBucket,
                                                                        IYeildCallBackFunc* callBack)=0;

	// ****************************************************************************
	//								CreateLayerList
	// 
	/// Creates a new layer list image.
	/// 
	/// \param rasterLayer  the created image
	/// \param width        the width of the image
	/// \param height       the height of the image
	/// 
	virtual MCCOMErr MCCOMAPI CreateLayerList						(	IShLayerList**					rasterLayer,
																		uint32							width,
																		uint32							height)=0;
};

/// \}


#endif
