/* Plug-in module utility routines */

/* Copyright 1993 by Adobe Systems, Inc.  All rights reserved. */

/* The routines in this module provide a collection of utilities for accessing
   the plug-in callback procedures and performing other useful tasks within
   plug-ins. */
 
#ifndef __PIUtilities__
#define __PIUtilities__

#include <StdDef.h>
#include <Types.h>

#include "PIGeneral.h"

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

/* The following routines provide shells around the buffer procs routines.
   These routines allow us to allocate buffers from Photoshop's memory
   without first telling Photoshop about it in the bufferSpace or maxSpace
   parameter in the interface record.  This can be useful when we need
   different sized buffers at different times. */

/* Are the buffer procs even available?  If not, the plug-in will have to
   put up a warning dialog to indicate that it requires Photoshop 2.5 or
   will have to work around this using the old memory management techniques
   documented in earlier versions of the plug-in kit.  tooNew is set if the
   procs version is newer than the plug-in.  The buffer procs version number
   is unlikely to change, but it is wise to test it anyway.  If tooNew is
   null, it will be ignored. */

Boolean HostBufferProcsAvailable (BufferProcs *procs, Boolean *tooNew);

/* The following dialog takes care of putting up the warning if the appropriate
   version of the buffer procs is not available. */

Boolean WarnHostBufferProcsAvailable (BufferProcs *procs);

/* How much space is available for buffers?  This space may be fragmented. */

int32 HostBufferSpace (BufferProcs *procs); 

/* Allocate a buffer of the appropriate size setting bufferID to the ID
   for the buffer.  If an error occurs, the error code will be returned
   and bufferID will be set to zero. */

OSErr HostAllocateBuffer (BufferProcs *procs, int32 size, BufferID *bufferID);

/* Free the buffer with the given ID. */

void HostFreeBuffer (BufferProcs *procs, BufferID bufferID);

/* Lock the buffer and return a pointer to its contents. */

Ptr HostLockBuffer (BufferProcs *procs, BufferID bufferID, Boolean moveHigh);

/* Unlock the buffer.  Lock and unlock calls manipulate a counter, so they
   must balance perfectly. */

void HostUnlockBuffer (BufferProcs *procs, BufferID bufferID);

/* The following routine allocates a buffer which is as tall as possible.  It
   takes as parameters, the desired rowBytes, the minimum height, the
   maximum height, and the fraction of the available buffer space to use
   expressed as 1/numBuffers.  It sets the actual height and bufferID
   parameters if successful. */

OSErr HostAllocateStripBuffer (BufferProcs *procs,
							   int32 rowBytes,
							   int16 minHeight,
							   int16 maxHeight,
							   int16 numBuffers,
							   int16 *actualHeight,
							   BufferID *bufferID);

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

/* The following macros assume that gStuff is defined somewhere as a pointer
   to the current interface record. */

#define BufferProcsAvailable(tooNew) \
	HostBufferProcsAvailable (gStuff->bufferProcs, tooNew)

#define WarnBufferProcsAvailable() \
	WarnHostBufferProcsAvailable (gStuff->bufferProcs)

#define BufferSpace() HostBufferSpace (gStuff->bufferProcs)

#define AllocateBuffer(size,bufferID) \
	HostAllocateBuffer (gStuff->bufferProcs, size, bufferID)

#define FreeBuffer(bufferID) \
	HostFreeBuffer (gStuff->bufferProcs, bufferID)

#define LockBuffer(bufferID,moveHigh) \
	HostLockBuffer (gStuff->bufferProcs, bufferID, moveHigh)

#define UnlockBuffer(bufferID) \
	HostUnlockBuffer (gStuff->bufferProcs, bufferID)

#define AllocateStripBuffer(rowBytes,minHeight,maxHeight,numBuffers,actualHeight,bufferID) \
	HostAllocateStripBuffer (gStuff->bufferProcs,\
							 rowBytes,\
							 minHeight,\
							 maxHeight,\
							 numBuffers,\
							 actualHeight,\
							 bufferID)

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

/* Similarly assuming gStuff to be defined, we define macros for testing
   for abort and for updating the progress bar. */

#ifdef __powerc

#define TestAbort() ((Boolean)CallUniversalProc((UniversalProcPtr)gStuff->abortProc, uppTestAbortProcInfo))

#define UpdateProgress(done,total) (CallUniversalProc((UniversalProcPtr)gStuff->progressProc, uppProgressProcInfo, (done), (total)))

#else

#define TestAbort() ((*gStuff->abortProc) ())

#define UpdateProgress(done,total) ((*gStuff->progressProc) (done, total))

#endif

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

/* Here is a corresponding set of routines and macros for the pseudo-resource
   callbacks. */
 
Boolean HostResourceProcsAvailable (ResourceProcs *procs, Boolean *tooNew);

Boolean WarnHostResourceProcsAvailable (ResourceProcs *procs);

int16 HostCountPIResources (ResourceProcs *procs, ResType type);

Handle HostGetPIResource (ResourceProcs *procs, ResType type, int16 index);

void HostDeletePIResource (ResourceProcs *procs, ResType type, int16 index);

OSErr HostAddPIResource (ResourceProcs *procs, ResType type, Handle data);

#define ResourceProcsAvailable(tooNew)										\
	HostResourceProcsAvailable (gStuff->resourceProcs, tooNew)
	
#define WarnResourceProcsAvailable()										\
	WarnHostResourceProcsAvailable (gStuff->resourceProcs)
	
#define CountPIResources(type)												\
	HostCountPIResources (gStuff->resourceProcs, type)
	
#define GetPIResource(type,index)											\
	HostGetPIResource (gStuff->resourceProcs, type, index)
	
#define DeletePIResource(type,index)										\
	HostDeletePIResource (gStuff->resourceProcs, type, index)
	
#define AddPIResource(type,data)											\
	HostAddPIResource (gStuff->resourceProcs, type, data)

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

/* And a set for the handle routines. */
 
Boolean HostHandleProcsAvailable (HandleProcs *procs, Boolean *tooNew);

Boolean WarnHostHandleProcsAvailable (HandleProcs *procs);

Handle HostNewHandle (HandleProcs *procs, int32 size);

void HostDisposeHandle (HandleProcs *procs, Handle h);

int32 HostGetHandleSize (HandleProcs *procs, Handle h);

OSErr HostSetHandleSize (HandleProcs *procs, Handle h, int32 newSize);

Ptr HostLockHandle (HandleProcs *procs, Handle h, Boolean moveHigh);

void HostUnlockHandle (HandleProcs *procs, Handle h);


#define HandleProcsAvailable(tooNew)										\
	HostHandleProcsAvailable (gStuff->handleProcs, tooNew)
	
#define WarnHandleProcsAvailable()											\
	WarnHandleProcsAvailable (gStuff->handleProcs);
	
#define PINewHandle(size)													\
	HostNewHandle (gStuff->handleProcs, size)
	
#define PIDisposeHandle(h)													\
	HostDisposeHandle (gStuff->handleProcs, h)
	
#define PIGetHandleSize(h)													\
	HostGetHandleSize (gStuff->handleProcs, h)
	
#define PISetHandleSize(h,size)												\
	HostSetHandleSize (gStuff->handleProcs, h, size)
	
#define PILockHandle(h,moveHigh)											\
	HostLockHandle (gStuff->handleProcs, h, moveHigh)
	
#define PIUnlockHandle(h)													\
	HostUnlockHandle (gStuff->handleProcs, h)
 
/*****************************************************************************/

#endif