/*---------------------------------------------------------
ISource.h : part of the ImgSource library.
Main ImgSource header file
This is the only file an application needs to #include
C/C++ users, see note below about Exported Symbols.
For ImgSource build configuration options, see ISConfig.h and ISTypes.h.
Credits:
Color quantization code modified from DL1Quant, by
Dennis Lee (denlee@ecf.utoronto.ca)
JPEG code from IJG v6b.
PNG code from LibPng
TIFF code from LibTiff
Compression from ZLib
TGA code from Timothy Bish
PCX code from Bob Johnson's PCXLib
Some crypto from Wei Dai's CryptLib 3.1
PAX code from Smaller Animals Software's PALib
TLA code from Smaller Animals Software's TLALib
RGBA Color quantization code modified from PNGQuant, by Greg Roelofs.
All other code, Smaller Animals Software.
This code copyright (c) 2000-2012, Smaller Animals Software, Inc..
No portion of this code may be copied or distributed without
permission of Smaller Animals Software, Inc..
http://www.smalleranimals.com
---------------------------------------------------------*/
#ifndef is5_SOURCEH
#define is5_SOURCEH
///////////////////////////////////////////////////////
// Exported Symbols
//
// C/C++ users of the DLL must #define IS50_USING_DLL (see below).
//
// Also, when using the DLL, all function names will start with "_" :
// Example: _is5_Initialize
//
// Users of the static libs should #undef IS50_USING_DLL, or simply comment-out the line below.
// When using the static libraries, function names will NOT start with "_"
// Example: is5_Initialize
//
// If you don't define IS50_USING_DLL correctly, you will get undefined symbol errors
// when you try to link.
//
///////////////////////////////////////////////////////
//#define IS50_USING_DLL
#ifdef __cplusplus
extern "C" {
#endif
///////////////////////////////////////////////////////
// source / destination manager function defintions
#include "ISTypes.h"
///////////////////////////////////////////////////////
// source / destination manager function defintions
#include "ISErrorCodes.h"
///////////////////////////////////////////////////////
// source / destination manager function defintions
#include "ISIOManagers.h"
////////////////////////////////////////////////////////
// file write function defintions
#include "ISFilesW.h"
////////////////////////////////////////////////////////
// single line file write function defintions
#include "ISFilesWL.h"
////////////////////////////////////////////////////////
// file read function defintions
#include "ISFilesR.h"
////////////////////////////////////////////////////////
// extended TIFF function defintions
#include "ISFilesTIFFExt.h"
////////////////////////////////////////////////////////
// single line file read function defintions
#include "ISFilesRL.h"
////////////////////////////////////////////////////////
// file dimension / bit depth function defintions
#include "ISFileDims.h"
////////////////////////////////////////////////////////
// file utilities (DPI, text, etc) function defintions
#include "ISFileUtil.h"
////////////////////////////////////////////////////////
// file utilities (DPI, text, etc) function defintions for JPEG
#include "ISFileUtilJPG.h"
////////////////////////////////////////////////////////
// image drawing function defintions
#include "ISImageDraw.h"
////////////////////////////////////////////////////////
// image processing function defintions
#include "ISImageProcess.h"
////////////////////////////////////////////////////////
// image histogram processing function defintions
#include "ISImageEnhance.h"
////////////////////////////////////////////////////////
// image resizing function defintions
#include "ISImageResize.h"
////////////////////////////////////////////////////////
// image rotation function defintions
#include "ISImageRotate.h"
////////////////////////////////////////////////////////
// image overlay function defintions
#include "ISImageOverlay.h"
////////////////////////////////////////////////////////
// image text draw function defintions
#include "ISImageText.h"
////////////////////////////////////////////////////////
// image effects function defintions
#include "ISImageEffects.h"
////////////////////////////////////////////////////////
// image FFT defintions
#include "ISImageFFT.h"
////////////////////////////////////////////////////////
// image morphology function defintions
#include "ISImageMorpho.h"
////////////////////////////////////////////////////////
// noise generation
#include "ISImageNoise.h"
////////////////////////////////////////////////////////
// image filter function defintions
#include "ISImageFilter.h"
////////////////////////////////////////////////////////
// image transformation function defintions
#include "ISImageTransformEffects.h"
////////////////////////////////////////////////////////
// EXIF data parser
#include "ISEXIF.h"
////////////////////////////////////////////////////////
// IPTC data parser
#include "ISIPTC.h"
////////////////////////////////////////////////////////
// PSD resource manager
#include "ISPSDResources.h"
////////////////////////////////////////////////////////
// Fast Fourier Transform functions
#include "ISImageFFT.h"
////////////////////////////////////////////////////////
// Generic zLib compression
#include "ISZLibComp.h"
////////////////////////////////////////////////////////
// general library function defintions
/*---------------------------------------------------------
is5_GetImgSourceVersion / _is5_GetImgSourceVersion
Purpose :
Get ImgSource version string
Param Use
------------------------------------
pVers receives version string
must be at least 20 chars.
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_GetImgSourceVersion )(char *buf);
/*---------------------------------------------------------
is5_Initialize / _is5_Initialize
Purpose :
Initialize the library.
Among other things, this initializes the ImgSource thread pool.
To initialize the library without using the thread pool, use
is5_InitializeEx.
Note:
You must call is5_Exit to free any resources allocated
by this library.
Note:
Do not call this function from DllMain - doing so will
likely cause your application to crash.
Param Use
------------------------------------
pKey library unlock key,
or any other string, if you don't have a key.
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_Initialize )(const char *pKey);
/*---------------------------------------------------------
is5_InitializeEx / _is5_InitializeEx
Purpose :
Initialize the library.
Among other things, this initializes the ImgSource thread pool.
If the thread pool is never initialized, multi-threaded
processing will be disabled.
See also: is5_Initialize
Note:
You must call is5_Exit to free any resources allocated
by this library.
Note:
If you are using the thread pool, do not call this
function from DllMain - doing so will likely cause
your application to crash.
Param Use
------------------------------------
pKey library unlock key,
or any other string, if you don't have a key.
uFlags bit purpose
--- -------
0 if set, the ImgSoruce thread pool will not
be started. all functions will run in their
single-threaded version.
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_InitializeEx )(const char *pKey, UINT32 uFlags);
/*---------------------------------------------------------
is5_Exit / _is5_Exit
Purpose :
Free any resources allocated by this library. This is
a process-level function. For thread resource release,
see is5_ThreadExit.
Do not call this unless you've called is5_Initialize first!
Note:
This function MUST be called when your application exits.
If you do not, you will certainly leak memory and resources,
and you may experience an application crash.
Note:
Do not call this function from DllMain. Doing so will
cause your application to crash on exit.
Note:
If this call seems to be taking a long time to return,
odds are good that you are calling it from DllMain, or
from a function which is called by DllMain. You must call
this before DllMain is called.
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_Exit )();
/*---------------------------------------------------------
is5_GetLastError / _is5_GetLastError
Purpose :
Get error code set by last function.
All functions in ImgSource set the global error value.
It is recommended that you test the error value often.
Return
------
Error value
---------------------------------------------------------*/
_ISDeclSpec UINT32 _ISCConv _ISFn( is5_GetLastError )();
/*---------------------------------------------------------
is5_SetLastError / _is5_SetLastError
Purpose :
Set the global ImgSource error code.
Param Use
------------------------------------
error error value to set
pCallerFunctionName name of calling function
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_SetLastError )(int error, const char *pCallerFunctionName);
/*---------------------------------------------------------
is5_GetErrorList / _is5_GetErrorList
Purpose :
ImgSource maintains a list of the last 50 errors it encountered.
This function retrieves that list as a single string with
errors separated by new lines.
The string is of this form:
Error 2 in is5_OpenFileSource (12:32:02)
Error 5 in is5_DrawRGB (12:32:02)
Also, there may be an optional bit of text on the end of the string.
Ex.:
Error #5 in is5_ReadJPG (04:22:04) [unsupported bit depth]
The information in the parenthesis is the current system
time in HH:MM:SS format.
Param Use
------------------------------------
hOutData receives HGLOBAL for the error string
puLen receives number of bytes allocated to the error string
uFlags unused
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_GetErrorList )(HGLOBAL *hOutData, UINT32 *puLen, UINT32 uFlags);
/*---------------------------------------------------------
is5_SetCallback / _is5_SetCallback
Purpose :
Set global callback function. This function is called
by all file read / write operations, and most image
processing calls. It is not called by image display
functions.
The callback function must be a function of this type :
BOOL CALLBACK MyCallbackFunction(const UINT32 uCurRow,
const UINT32 uTotalRows,
const IS_CALLBACK_DATA uUserData)
{
if (time to quit)
{
return FALSE;
}
return TRUE;
}
Set it with:
is5_SetCallback(MyCallbackFunction, uUserData);
The library will also call the callback function once
per row for most image processing calls. For some complex
operations, it may be called a fixed number of times,
regardless of image size.
Operations which do not operate on image buffers are not
"image processing calls" and so, these won't use the callback
function. This includes calls such as JPG and PNG text calls,
PNG gamma and background operations, DPI queries, error
queries, etc..
Basically, if there is no loop over pixels, there is no
callback call. However, this does not mean that *all*
operations which do have a pixel loop use the callback
function; some don't. Check the function comments in this
file, to be sure.
If the callback function returns FALSE the operation aborts and
is5_GetLastError will return IS_ERR_CALLBACKCANCEL
You can use this to monitor the progress of ImgSource operations.
It is not neccessary for you to use this function. If you
do not set the callback function or pass a NULL to this call,
no callback will be performed.
The callback is thread safe. Each thread can have its own
callback function.
Parameter Use
------------------------------------
pCallback pointer to callback function
uUserData user data. this data is thread safe.
Return
------
Error value
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_SetCallback )(ISCALLBACKPTR pCallback, IS_CALLBACK_DATA uUserData);
/*---------------------------------------------------------
is5_GetCallback / _is5_GetCallback
Purpose :
Retrieve the callback state.
Parameter Use
------------------------------------
puUserData receives user data.
Return
------
pointer to callback function
---------------------------------------------------------*/
_ISDeclSpec ISCALLBACKPTR _ISCConv _ISFn( is5_GetCallback )(IS_CALLBACK_DATA *puUserData);
/*---------------------------------------------------------
is5_SetErrorCallback / _is5_SetErrorCallback
Purpose :
Set a callback function to be called when an ImgSource function
encounters an error during processing. This can be useful
for diagnostics or application logging.
The callback must be a function of this type:
BOOL myErrorCallback(UINT32 uErrorCode,
const char *pErrorText,
const IS_CALLBACK_DATA uUserData)
{
// uErrorCode is the error value. it's the
// same value you'll get when you call is5_GetLastError.
// pErrorText is typically the name of the function which
// is setting the error
// uUserData is the value you passed to is5_SetErrorCallback
printf("function %s set an error value of %d\n", pErrorText, uErrorCode);
// you should return TRUE, always.
return TRUE;
}
Parameter Use
------------------------------------
pCallback callback function pointer
userData user-defined data which will
be passed to your callback function.
Return
------
none
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_SetErrorCallback )(ISERRORCALLBACK pCallback, IS_CALLBACK_DATA userData);
/*---------------------------------------------------------
is5_ThreadExit / _is5_ThreadExit
Purpose :
Free any ImgSource resources associated with this
thread.
These resources include JPG and PNG metadata, error
state info and thread-local storage areas (TLS).
This function is useful in applications that are heavily
multithreaded. If you do not call this when your thread
exits, any resources ImgSource has associated it may
remain in memory until your process exits.
So, it it not a fatal mistake to not call this when a thread
exits. Not calling this simply means any resources allocated
for the thread will remain allocated until the parent process exits.
It is safe to call this even if the thread has not yet called
any other ImgSource functions.
This should be the last ImgSource call that your thread makes.
This function is not available in the DLL. The DLL
will handle thread cleanup by itself.
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_ThreadExit )();
/*---------------------------------------------------------
is5_GetExtHook / _is5_GetExtHook
Purpose :
Get a hook object to initialize an add-on library.
The hook object allows the add-on library to access ImgSource's
I/O functions (to allow files to be read and written),
provides access to the progress callbacks (is5_SetCallback),
provides access to the file reading memory allocation callbacks
(is5_SetFileReadAllocCallbacks) and provides access to the
ImgSource global error value. Add-on libraries will use
these services in their own operation.
Usage:
HISEXTHK hHook = is5_GetExtHook(0);
AddOnLibrary_SetImgSourceHook(hHook);
GlobalFree(hHook);
Param Use
------------------------------------
uFlags unused
Return
------
A HISEXTHK object to be passed to an add-on library.
After passing this to the add-on library, you must free this
memory by using GlobalFree.
---------------------------------------------------------*/
_ISDeclSpec HISEXTHK _ISCConv _ISFn( is5_GetExtHook )(UINT32 uFlags);
/*---------------------------------------------------------
is5_SetDebugMessageLevel / _is5_SetDebugMessageLevel
Purpose :
Control the level of debug messages shown by the library.
These messages are written to the debug console (they are
not popup windows or logfile messages).
This only affects debug builds, since no debug messages
are shown in release builds.
Param Use
------------------------------------
uLevel 0: show all messages - verbose
1: show informational, warning and critical messages
2: show warning and critical messages (default)
3: show critical messages only
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_SetDebugMessageLevel )(UINT32 uLevel);
/*---------------------------------------------------------
is5_SwapLong / _is5_SwapLong
Purpose :
Convert a 32-bit integer from Intel byte order to Motorola
byte order, and vice versa.
Param Use
------------------------------------
pLong 32-bit integer to swap
Return
------
none
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_SwapLong )(UINT32 *pLong);
/*---------------------------------------------------------
is5_SwapShort / _is5_SwapShort
Purpose :
Convert a 16-bit integer from Intel byte order to Motorola
byte order, and vice versa.
Param Use
------------------------------------
pShort 16-bit integer to swap
Return
------
none
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_SwapShort )(ISUINT16 *pShort);
/*---------------------------------------------------------
is5_DisableMMXFunctions / _is5_DisableMMXFunctions
Purpose :
By default, ImgSource will use MMX/SSE-optimized functions
wherever possible. This function will disable those optimizations.
Param Use
------------------------------------
bUseMMX TRUE (1) to enable MMX, 0 to disable
Return
------
none
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn( is5_DisableMMXFunctions )(BOOL bUseMMX);
/*---------------------------------------------------------
is5_IsMMXSupported / _is5_IsMMXSupported
Purpose :
Test to see if the CPU supports Intel's MMX instructions.
Param Use
------------------------------------
none
Return
------
TRUE if MMX is supported
---------------------------------------------------------*/
_ISDeclSpec BOOL _ISCConv _ISFn( is5_IsMMXSupported )();
/*---------------------------------------------------------
is5_SetWorkerThreadCount / _is5_SetWorkerThreadCount
Purpose :
Sets the number of worker threads for functions with
multithreaded processing options.
The minimum is 1. The maximum is 255.
The default worker thread count is 4.
Setting this to 1 disables all multi-threading.
These threads are pulled from threads in the global ImgSource
thread pool. If you set a number that is greater than the
number of threads in the thread pool, tasks will be queued
and then handled as pool threads become available.
See is5_SetWorkerThreadCallbackFrequency, is5_SetWorkerThreadTimeout,
is5_SetWorkerThreadPoolSize, is5_Initialize.
Param Use
------------------------------------
n number of worker threads
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn(is5_SetWorkerThreadCount)(UINT32 n);
/*---------------------------------------------------------
is5_SetWorkerThreadCallbackFrequency / _is5_SetWorkerThreadCallbackFrequency
Purpose :
Functions with multithreaded options do not call the
global progress callback (is5_SetCallback) once for every
line processed. Rather they are, in effect, called on a timer.
This function controls how frequently the callbacks happen.
Note:
The ImgSource multi-threaded callback model is:
1. Threads are created in suspended mode and thread parameters are set.
2. All threads are launched.
3. The thread controller Waits on all threads for the time given here.
4. If all threads finish before the Wait is over, the function exits with
no callbacks.
5. If the Wait expires but one or more threads are still working,
the callback is called, and a new Wait begins.
For fast operations, it's entirely likely that a mutli-threaded function
will finish before any callbacks are called.
The default is 200ms. Longer times reduce the number of times the
callback is called. Shorter times increase the nubmer of callbacks.
See is5_SetWorkerThreadCount, is5_SetWorkerThreadTimeout,
is5_SetWorkerThreadPoolSize.
Param Use
------------------------------------
ms number of milliseconds to Wait between callbacks
Return
------
pDest
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn(is5_SetWorkerThreadCallbackFrequency)(UINT32 ms);
/*---------------------------------------------------------
is5_SetWorkerThreadTimeout / _is5_SetWorkerThreadTimeout
Purpose :
This sets the thread timeout length for functions with
multithreaded options. If a worker thread fails to finish
when the timeout happens, the thread will be terminated.
Note:
This is only used when there is no global progress
callback set (is5_SetCallback).
The default is infinity - never timeout.
See is5_SetWorkerThreadCount, is5_SetWorkerThreadCallbackFrequency,
is5_SetWorkerThreadPoolSize.
Param Use
------------------------------------
ms number of milliseconds for the timeout
Return
------
pDest
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn(is5_SetWorkerThreadTimeout)(UINT32 ms);
/*---------------------------------------------------------
is5_SetWorkerThreadPoolSize / _is5_SetWorkerThreadPoolSize
Purpose :
This sets the size of the ImgSource global thread pool.
This function gives all pool threads a 2 second timeout period
to let any pending jobs finish. After that, all existing
pool threads are terminated and the specified number of new threads
is created. Be careful to call this only when there are no
pending ImgSource calls.
The default worker thread pool size is eight, and these threads
are started when the library is initialized (when the ImgSource
DLL is loaded, or when a statically-linked application is launched).
They are terminated when the DLL unloads (or when the
statically-linked application terminates).
The minimum thread pool size is 2. The maximum is 255.
These threads will remain idle until one of the ImgSource
multithreaded functions is called. Then, up to is5_SetWorkerThreadCount
of these threads will be activated.
If the value set with is5_SetWorkerThreadCount is greater than the
pool size, or if there are more jobs waiting than the number of
available threads, waiting jobs will be queued.
The thread pool is global to an instance of ImgSource. All application
threads which call into ImgSource share the thread pool.
See is5_SetWorkerThreadCallbackFrequency, is5_SetWorkerThreadTimeout,
is5_SetWorkerThreadCount, is5_Initialize.
Param Use
------------------------------------
n number of worker threads in the pool
---------------------------------------------------------*/
_ISDeclSpec void _ISCConv _ISFn(is5_SetWorkerThreadPoolSize)(UINT32 n);
/*---------------------------------------------------------
is5_MemCopy / _is5_MemCopy
As of v5.0.2.7, this function has been deprecated.
This will use the standard C memcpy.
---------------------------------------------------------*/
_ISDeclSpec void* _ISCConv _ISFn( is5_MemCopy )(void *pDest, const void *pSrc, size_t n);
/*---------------------------------------------------------
is5_UseMMXMemcopy / _is5_UseMMXMemcopy
As of v5.0.2.7, this function has been deprecated.
Calling it has no effect.
Deprecated.
---------------------------------------------------------*/
_ISDeclSpec BOOL _ISCConv _ISFn( is5_UseMMXMemcopy )(BOOL bUseMMXMemcopy);
#ifdef __cplusplus
}
#endif
#endif
Submit an article or tip