/*********************************************************/
/* This source code copyright (c) 1991-2001, Aaron Giles */
/* See the Read Me file for licensing information.       */
/* Contact email: mac@aarongiles.com                     */
/*********************************************************/

#ifndef __JPEGVIEWPLUGIN__
#define __JPEGVIEWPLUGIN__

/*

Function descriptions:

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

plugInAbout: Display the plug-in's about box

	 -->	plugInResFile	file specification record of the plug-in
	 -->	plugInGlobals	handle to the plug-in's globals (from plugInOpen)

	returns:	noErr				-- initialization was successful
				memFullErr			-- not enough memory to identify the image
				other errors		-- any other problems

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

plugInInitialize: Initialize the plug in; called once when the plug-in is initialized

	 -->	plugInResFile	file specification record of the plug-in
	<--		plugInInfo		handle to a plug-in information record
	<--		plugInGlobals	handle to the plug-in's globals

	returns:	noErr				-- initialization was successful
				memFullErr			-- not enough memory to initialize the plug-in
				errInitializeFailed	-- initialization failed

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

plugInIdentify: Attempt to identify the image

	 -->	plugInResFile	file specification record of the plug-in
	 -->	plugInGlobals	handle to the plug-in's globals (from plugInOpen)
	<-->	imageData		handle to the currently-loaded data; guaranteed to be at
								least 1024 bytes long; more can be loaded if necessary
	 -->	dfRefNum		reference number of the file's data fork
	 -->	imageFile		file specification record of the file

	returns:	noErr 				-- the image was identified correctly
				memFullErr			-- not enough memory to identify the image
				errInvalidImage 	-- the image was not identified
				other errors		-- error reading the file

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

plugInLoad: Load the image data

	 -->	plugInResFile	file specification record of the plug-in
	 -->	plugInGlobals	handle to the plug-in's globals (from plugInOpen)
	<-->	imageData		handle to the image data; initially contains data from the
								data fork
	 -->	dfRefNum		reference number of the file's data fork
	 -->	imageFile		file specification record of the file
	
	returns:	noErr 				-- the image was loaded successfully
				memFullErr			-- not enough memory to load the image
				errInvalidImage 	-- the image was not identified
				other errors		-- error reading the file

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

plugInOpen: Open the image after loading, by pulling vital information from the data

	 -->	plugInResFile	file specification record of the plug-in
	 -->	plugInGlobals	handle to the plug-in's globals (from plugInOpen)
	<--		imageGlobals	handle to the plug-in's globals for this image
	<--		horizontalDPI	horizontal resolution of the image (in DPI) as a Fixed
	<--		verticalDPI		vertical resolution of the image (in DPI) as a Fixed
	<--		globalRect		rectangle, in pixels, of the full-sized image
	<--		croppedRect		rectangle, in pixels, of the initial cropped area
	<--		imageDepth		depth of the image, or 32+depth for grayscale images
	<--		imageColors		handle to a color table containing the image colors, or nil
								if none
	<--		compressionType	index in the plugInInfo record of the compression info
	<--		compressionDesc	description of the compression (as seen in the stats), or nil
								to take the description from the plugInInfo
	<--		imageComments	handle to the image's comments
	
	returns:	noErr				-- the image was recognized successfully
				memFullErr			-- not enough memory to open the image
				errInvalidImage		-- an error was found in the image data
				other errors		-- any other problems

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

plugInDraw: Draw the image to the current port

	 -->	plugInResFile	file specification record of the plug-in
	 -->	plugInGlobals	handle to the plug-in's globals (from plugInOpen)
	 -->	imageGlobals	handle to the plug-in's globals for this image
	 -->	imageData		handle to the image data
	 -->	horizontalDPI	horizontal resolution of the image (in DPI) as a Fixed
	 -->	verticalDPI		vertical resolution of the image (in DPI) as a Fixed
	 -->	globalRect		rectangle, in pixels, of the full-sized image
	 -->	croppedRect		rectangle, in pixels, of the initial cropped area
	 -->	imageDepth		depth of the image, or 32+depth for grayscale images
	 -->	imageColors		handle to a color table containing the image colors, or nil
								if none
	 -->	compressionType	index in the plugInInfo record of the compression info
	 -->	imageComments	handle to the image's comments
	 -->	progressProc	a progress procedure record; call this occasionally to 
	 							update the progress display

	returns:	noErr				-- the image was drawn successfully
				memFullErr			-- not enough memory to draw the image
				errInvalidImage		-- an error was found in the image data
				other errors		-- any other problems

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

plugInConvert: Convert the image to a different format

	 -->	plugInResFile	file specification record of the plug-in
	 -->	plugInGlobals	handle to the plug-in's globals (from plugInOpen)
	 -->	imageGlobals	handle to the plug-in's globals for this image
... (not finished yet)

*/


typedef unsigned short PlugInFlags;
typedef unsigned short CompressionFlags;
typedef OSErr PlugInError;

typedef struct CompressionInfo {
	Str31 compressionName;					// the name as it should appear in the menu
	CompressionFlags compressionParams;		// the compression support flags
} CompressionInfo, *CompressionInfoPtr, **CompressionInfoHandle;

typedef struct PlugInInfo {
	PlugInFlags plugInParams;				// the plug-in's parameters
	short compressionMethods;				// the number of compression methods supported
	CompressionInfo compressionInfo[1];		// list of compression info records
} PlugInInfo, *PlugInInfoPtr, **PlugInInfoHandle;

typedef struct PlugInData {
	FSSpec plugInResFile;					// file specification of the resource file
	Handle plugInGlobals;					// handle to the plug-in's globals
	PlugInInfoHandle plugInInfo;			// handle to the plug-in information

	Handle imageData;						// handle to the current image data
	short dfRefNum;							// reference number of the file's data fork
	FSSpec imageFile;						// file specification record of the image file

	Handle imageGlobals;					// handle to the plug-in's image globals
	Fixed horizontalDPI;					// horizontal resolution of the image
	Fixed verticalDPI;						// vertical resolution of the image
	Rect globalRect;						// rectangle of the full-sized image
	Rect croppedRect;						// rectangle of the initial cropped area
	short imageDepth;						// depth of the image, or 32+depth for grays
	CTabHandle imageColors;					// handle to the image color table
	short compressionType;					// index in the plugInInfo of compression
	Str64 compressionDesc;					// description of the compression (for stats)
	Handle imageComments;					// handle to the image's comments

	NestedProgress drawProgress;			// the progress function for drawing
	Handle drawPrivates;					// private data structure for drawing

} PlugInData, *PlugInDataPtr, **PlugInDataHandle;

enum {
	pifSupportsOpening = 0x0001,			// i.e., identify, load, draw
	pifSupportsConverting = 0x0002,			// i.e., convert, save
	pifSupportsCompressing = 0x0004,		// i.e., compress, save
	pifSupportsPreviews = 0x0008,			// should we offer preview option?
	pifSupportsReducedColors = 0x0010,		// should we offer color reduction saving?
};

enum {
	cfCanSaveInMillions = 0x0001,			// can we compress in millions of colors?
	cfCanSaveInThousands = 0x0002,			// can we compress in thousands of colors?
	cfCanSaveIn256Colors = 0x0004,			// can we compress in 256 colors?
	cfCanSaveIn256Grays = 0x0008,			// can we compress in 256 grays?
};

enum {
	errInvalidImage = 1,
	errInitializeFailed = 2,
	errCantConvert = 3
};

// Examples:JPEG = pifSupportsOpening + pifSupportsSaving + pifSupportsPreviews +
//					pifSupportsLossyCompression + pifCanSaveInMillions + 
//					pifCanSaveIn256Grays
//
//			PICT = pifSupportsOpening + pifSupportsSaving + pifSupportsPreviews +
//					pifSupportsReducedColors + pifSupportsLosslessCompression +
//					pifSupportsLossyCompression + pifSupportsNoCompression +
//					pifSupportsMultipleCompression + pifCanSaveInMillions +
//					pifCanSaveInThousands + pifCanSaveIn256Colors + pifCanSaveIn256Grays
//
//			GIF = pifSupportsOpening + pifSupportsSaving + 
//					pifSupportsLosslessCompression + pifCanSaveIn256Colors

enum {
	plugInAbout,
	plugInInitialize,
	plugInIdentify,
	plugInLoad,
	plugInOpen,
	plugInDraw,
	plugInConvert,
	plugInCompress,
	plugInSave,
	plugInClose,
	plugInQuit
};

typedef pascal OSErr (*PlugInDispatcher)(short selector, PlugInDataHandle theData);

#endif