/********************************************************** 
** Copyright 1999 Earth Resource Mapping Ltd.
** This document contains proprietary source code of
** Earth Resource Mapping Ltd, and can only be used under
** one of the three licenses as described in the 
** license.txt file supplied with this distribution. 
** See separate license.txt file for license details 
** and conditions.
**
** This software is covered by US patent #6,442,298,
** #6,102,897 and #6,633,688.  Rights to use these patents 
** is included in the license agreements.
** 
** FILE:   	NCSECWCompessClient.h
** CREATED:	Thu 19/08/1999
** AUTHOR: 	Simon Cope
** PURPOSE:	Public Interface library to compress ECW v2.0 image files
** EDITS:
** [01] sjc 08Dec1999	Updated comments
**
********************************************************/

/** @file NCSECWCompressClient.h */
#ifndef NCSECWCOMPRESSCLIENT_H
#define NCSECWCOMPRESSCLIENT_H

#ifndef NCSECWCLIENT_H
#include "NCSECWClient.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

#ifndef NCSTYPES_H
#include "NCSTypes.h"
#endif
#ifndef NCSERRORS_H
#include "NCSErrors.h"
#endif

#define ERSWAVE_VERSION 2
#define ERSWAVE_VERSION_STRING	"2.0"		/* should be in sync with the above */

/** 
 *  @enum
 *	An enumerated type specifying the format of the compressed data. Currently greyscale, RGB
 *	and luminance-chrominance formats are supported.  This will later need expanding to include 
 *	multiband formats such as CMYK.
 */
typedef enum {
	/** The compressed data is unformatted */
	COMPRESS_NONE		= NCSCS_NONE,
	/** Greyscale format, single band */
	COMPRESS_UINT8		= NCSCS_GREYSCALE,
	/** JPEG standard YUV digital format, three band */
	COMPRESS_YUV		= NCSCS_YUV,
	/** Multiband format */
	COMPRESS_MULTI		= NCSCS_MULTIBAND,
	/** RGB images (converted to COMPRESS_YUV internally) */
	COMPRESS_RGB		= NCSCS_sRGB			
} CompressFormat;

/**	
 *	@enum
 *	An enumerated type allowing the user to hint at an appropriate compression scheme.  The 
 *	value is a guideline for the SDK compression functions.
 */
typedef enum {
	/** No compression hint */
	COMPRESS_HINT_NONE	= 0,
	/** Do the fastest compression possible */
	COMPRESS_HINT_FAST	= 1,
	/** Try to achieve the maximum possible compression ratio */
	COMPRESS_HINT_BEST	= 2,
	/** Optimise compression process for later Internet use of the compressed file */
	COMPRESS_HINT_INTERNET = 3
} CompressHint;

/** @def Maximum length of a datum definition string */
#define ECW_MAX_DATUM_LEN		16
#ifndef ECW_MAX_PROJECTION_LEN
/** @def Maximum length of a projection definition string */
#define ECW_MAX_PROJECTION_LEN	16
#endif

/** @def X dimension of the default (and preferred) block size */
#define X_BLOCK_SIZE	64
/** @def Y dimension of the default (and preferred) block size */
#define	Y_BLOCK_SIZE	64

/** 
 *	@struct
 *	This structure contains information used when compressing raster data 
 *	to an output ECW file.  Most of the values have sensible defaults so users
 *	need only customise those of significance to their application.  Certain 
 *	of these values must always be specified in the client code, namely 
 *	fTargetCompression, nInOutSizeX, nInOutSizeY, nInputBands, and pReadCallback.
 *
 *	Once compression is complete certain statistics are calculated and added 
 *	to this structure.  These include the time taken, the output file size in 
 *	bytes, the actual compression ratio achieved, and the MB/s throughput of the 
 *	process.
 */
typedef struct NCSEcwCompressClient {
	/*
	** These fields are populated by the compression client
	*/
	/** If this is specified but the output file is not, a default output filename will be created.
	 *	Otherwise this field is unused.
	 */
	char	szInputFilename[MAX_PATH];			
	/** An output filename must be specified if no input filename is specified */
	char	szOutputFilename[MAX_PATH];	
	/** The target compression ratio - must be specified */
	IEEE4			fTargetCompression;
	/**	The compression format to use.  See the related enumerated type definition */
	CompressFormat	eCompressFormat;
	/** A guideline for an appropriate compression scheme to use.  This currently has 
	 *	no effect, though the default value is COMPRESS_HINT_INTERNET.  Reserved for
	 *	future use, see the related enumerated type definition 
	 */
	CompressHint	eCompressHint;
	/** X dimension of the block size to use.  Can be 64, 128, 256, 512, 1024, or 2048.
	 *	The default for these is set to 64 which produces preferred performance over the internet.
	 */
	UINT32			nBlockSizeX;
	/** Y dimension of the block size to use.  Can be 64, 128, 256, 512, 1024, or 2048.
	 *	The default for these is set to 64 which produces preferred performance over the internet.
	 */
	UINT32			nBlockSizeY;				/* Y Block size (64, 128, 256, 512)					*/
	/** Number of cells of input data and compressed file in the X direction - must be specified */
	UINT32			nInOutSizeX;
	/** Number of cells of input data and compressed file in the Y direction - must be specified */
	UINT32			nInOutSizeY;
	/** Number of bands in the input data - must be specified */
	UINT32			nInputBands;
	/** Number of bands in the output file - should not generally be specified */
	UINT32			nOutputBands;
	/** Size of the input file in bytes - should not be specified, it will be determined automatically. */
	UINT64			nInputSize;
	/** Optional field specifying the cell size in the X direction in eCellSizeUnits */
	IEEE8			fCellIncrementX;
	/** Optional field specifying the cell size in the Y direction in eCellSizeUnits */
	IEEE8			fCellIncrementY;
	/** Optional field specifying the X world origin of the input data in eCellSizeUnits */
	IEEE8			fOriginX;
	/** Optional field specifying the Y world origin of the input data in eCellSizeUnits */
	IEEE8			fOriginY;
	/** Optional field specifying the units in which world cell sizes are specified, e.g. meters, feet */
	CellSizeUnits	eCellSizeUnits;
	/** ER Mapper GDT style datum string */
	char			szDatum[ECW_MAX_DATUM_LEN];
	/** ER Mapper GDT style projection string */
	char			szProjection[ECW_MAX_PROJECTION_LEN];
	/** Callback function used to obtain lines of band data from the input data - must be specified */
	BOOLEAN			(*pReadCallback) (struct NCSEcwCompressClient *pClient,
									  UINT32 nNextLine,
									  IEEE4 **ppInputArray);
	/** Optional status callback function to track the progress of the compression process */
	void			(*pStatusCallback) (struct NCSEcwCompressClient *pClient,
										UINT32 nCurrentLine);				
	/** Optional cancel callback function which can be used to cancel a compression process */
	BOOLEAN			(*pCancelCallback) (struct NCSEcwCompressClient *pClient);
	/** (void *) Pointer to any private data you need to access in the three callback functions */
	void			*pClientData;
	/** Created by NCSEcwCompressOpen() */
	struct			EcwCompressionTask *pTask;
	/*
	** The remaining fields are populated by NCSEcwCompressClose() 
	*/
	/** Actual compression rate achieved - ratio of input data size to output file size */
	IEEE4			fActualCompression;
	/** Time taken to perform the complete compression, in seconds */
	IEEE8			fCompressionSeconds;
	/** MB/s throughput during the compression process */
	IEEE8			fCompressionMBSec;
	/** Total size of the output file in bytes */
	UINT64			nOutputSize;
} NCSEcwCompressClient;

/** 
 *	Allocate a new CompressionClient structure and fill in defaults 
 *
 *	@return					A pointer to memory allocated to an NCSEcwCompressClient structure
 */
NCSEcwCompressClient * NCS_CALL NCSEcwCompressAllocClient(void);
/**	
 *	Having set compression parameters, initialise the compression process
 *
 *	@param[in,out]	pInfo				The NCSEcwCompressClient structure containing the compression parameters 
 *	@param[in]		bCalculateSizesOnly	Which output statistics to calculate 
 *	@return								NCSError value, NCS_SUCCESS or any applicable error code
 */
NCSError NCS_CALL NCSEcwCompressOpen(NCSEcwCompressClient *pInfo, BOOLEAN bCalculateSizesOnly); 
/**	
 *	Start the compression process based on these parameters
 *
 *	@param[in,out]	pInfo				The NCSEcwCompressClient structure for this compression process
 *	@return								NCSError value, NCS_SUCCESS or any applicable error code
 */
NCSError NCS_CALL NCSEcwCompress(NCSEcwCompressClient *pInfo);
/** 
 *	Having completed compression, close, calculate output statistics, and clean up
 *
 *	@param[in,out]	pInfo				The NCSEcwCompressClient structure for this compression process
 *	@return								NCSError value, NCS_SUCCESS or any applicable error code
 */
NCSError NCS_CALL NCSEcwCompressClose(NCSEcwCompressClient *pInfo);
/**	
 *	Free the memory allocated to the NCSEcwCompressClient structure
 *
 *	@param[in,out]	pInfo				The structure to free
 *	@return								NCSError value, NCS_SUCCESS or any applicable error code
 */
NCSError NCS_CALL NCSEcwCompressFreeClient(NCSEcwCompressClient *pInfo);

typedef struct {
	UINT8				nVersion;			// ECW file version == ERSWAVE_VERSION
	CellSizeUnits		eCellSizeUnits;		// Units used for pixel size
	IEEE8				fCellIncrementX;	// Increment in CellSizeUnits in X direction. May be negative. Will never be zero
	IEEE8				fCellIncrementY;	// Increment in CellSizeUnits in Y direction. May be negative. Will never be zero
	IEEE8				fOriginX;			// World X origin for top-left corner of top-left cell, in CellSizeUnits
	IEEE8				fOriginY;			// World Y origin for top-left corner of top-left cell, in CellSizeUnits
	char				*szDatum;			// ER Mapper style Datum name string, e.g. "RAW" or "NAD27". Will never be NULL
	char				*szProjection;		// ER Mapper style Projection name string, e.g. "RAW" or "WGS84". Will never be NULL

	BOOLEAN				bCompressedOffsetTable; // Is the block table compressed
} NCSEcwEditInfo;

NCSError NCS_CALL NCSEcwEditReadInfo(char *pFilename, NCSEcwEditInfo **ppInfo);
NCSError NCS_CALL NCSEcwEditWriteInfo(char *pFilename, NCSEcwEditInfo *pInfo, void (*pProgressFunc)(UINT64 nTotal, UINT64 nWritten, void *pClientData), BOOLEAN (*pCancelFunc)(void *pClientData), void *pClientData);
NCSError NCS_CALL NCSEcwEditFreeInfo(NCSEcwEditInfo *pInfo);

#ifdef __cplusplus
}
#endif

#endif /* NCSECWCOMPRESSCLIENT_H */