Express Compression JPEG Application Program Interface (ECJAPI)

(c) 1993,1994 Expressed Compression Laboratories
********************************************************************************

ECJ_Decode (2.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

HANDLE ECJ_Decode( lpstrfilename, wParam, lParam, lpfnECJ_CallBack )

LPSTR	lpstrFileName;		/* name of file to decode */
WORD	wParam;			/* attributes */
LONG	lParam;			/* optional parameters */
ECJCB	lpfnECJ_CallBack;	/* call back routine */

ECJ_Decode decodes the specified JPEG file and returns a device independent
bitmap (DIB).

Parameter	 Description
---------------------------------------------------------------------------
lpstrFileName	 Points to a null-terminated string that names the JPEG
		 file to be decoded.

wParam		 Specifies how decoding shall proceed. This parameter
		 can be a combination of the following values.

		 Value		Meaning
		 -------------- -------------------------------------------
		 ECJ_GRAY_ONLY	Create a gray only DIB.
		 ECJ_24_BITS	Create a 24 bit DIB.
		 ECJ_2_PASS	Use two-pass 24 to 8 bit colour quantisation.
		 ECJ_DITHER	Use FS dithering in 2-pass color quantisation.
		 ECJ_HALF_SIZE	Shrink the dimensions of the picture by half.
		 ECJ_4_SIZE	Shrink the dimensions of the picture by 1/4th.
		 ECJ_8_SIZE	Shrink the dimensions of the picture by 1/8th.
		 ECJ_AUTO_SIZE	Automatically shrink the dimensions of the
				picture when appropriate.

		 ECJ_DITHER can only be used in conjunction with ECJ_2_PASS.
		 ECJ_GRAY_ONLY, ECJ_24_BITS and ECJ_2_PASS are mutually
		 exclusive. ECJ_HALF_SIZE, ECJ_4_SIZE and ECJ_8_SIZE are
		 mutually exclusive, while ECJ_AUTO_SIZE takes precedence over
		 all of them.
		 By default (with wParam = 0) ECJ_Decode creates an 8 bit DIB,
		 using single pass colour quantisation with ordered dithering
		 when appropriate.

lParam		 Bits 24 to 30 can be used as an optional 7 bit label, which
		 is passed back to the client during callback, for the purpose
		 of uniquely identifying each call to ECJ_Decode when multiple
		 calls are made in parallel.

lpfnECJ_CallBack Specifies the procedure-instance address of the callback
		 procedure. ECJ_Decode sends messages and periodically passes
		 control back to the client via the ECJ callback procedure.
		 Setting this parameter to NULL disables the callback
		 mechanism.
		 For more information see the description of the ECJ_CallBack
		 function.

Returns
=======
The return value is the handle to the DIB if the function is successful.
Otherwise, it is NULL.

See Also
========
ECJ_CallBack

********************************************************************************

ECJ_DecodeMem (2.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

HANDLE ECJ_DecodeMem( hStream, dwStreamLen, wParam, lParam, lpfnECJ_CallBack )

HGLOBAL	hStream;		/* handle to bitstream in memory */
DWORD	dwStreamLen;		/* size of bitstream in bytes */
WORD	wParam;			/* attributes */
LONG	lParam;			/* optional parameters */
ECJCB	lpfnECJ_CallBack;	/* call back routine */

ECJ_DecodeMem decodes the specified JPEG file and returns a device independent
bitmap (DIB). ECJ_DecodeMem is essentially the same as ECJ_Decode, except
that instead of taking a filename it takes a memory object as input.

Parameter	 Description
---------------------------------------------------------------------------
hStream		 Global handle to memory object containing bitstream
		 to be decoded.

dwStreamLen	 Size of the bitstream in bytes.

See ECJ_Decode for explanations on the rest of the parameters.

********************************************************************************

ECJ_Crop (2.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

HANDLE ECJ_Crop ( lpstrInFileName, hInStream, lParam, dwInStreamLen,
		  lprectCropRect, lpstrOutFileName, lpdwOutStreamLen,
		  lpfnECJ_CallBack )

LPSTR	lpstrInFileName;	/* name of the source file */
HANDLE	hInStream;		/* handle to input bitstream in memory */
DWORD	dwInStreamLen;		/* size of input bitstream in bytes */
LONG	lParam;			/* optional parameter */
LPRECT	lprectCropRect;		/* cropping rectangle */
LPSTR	lpstrOutFileName;	/* name of output file */
LPDWORD lpdwOutStreamLen;	/* length of output bitstream */
ECJCB	lpfnECJ_CallBack;	/* call back routine */

ECJ_Crop creats a windowed version of the input JPEG image, in accordance
with the specfied cropping rectangle. This is achieved by direct manipulation
of the input bitstream in the DCT domain, and no additional distortion is
introduced in the process. The input bitstream is contained either in a source
file or in a memory object. The output bitstream can be written directly to
a specified file, or can be returned as a memory object.

Parameter	 Description
---------------------------------------------------------------------------
lpstrInFileName	 Points to a null-terminated string that names the source
		 JPEG file. It should be NULL if the input is contained in
		 a memory object.

hInStream	 Global handle to memory object containing the source JPEG
		 bitstream. It should be NULL if the input is contained in a
		 file.

lParam		 Bits 24 to 30 can be used as an optional 7 bit label, which
		 is passed back to the client during callback, for the purpose
		 of uniquely identifying each call to ECJ_Decode when multiple
		 calls are made in parallel.

dwInStreamLen	 Indicates the size of the bitstream in bytes if the input
		 is to be taken from memory.

lprectCropRect	 The cropping rectangle. lprectCropRect.left specifies the
		 number of columns, in units of 8, that should be removed
		 from the left of the picture. lprectCropRect.right specifies
		 the number of columns, in units of 8, that should be removed
		 from the right edge of the picture. lprectCropRect.top and
		 lprectCropRect.right have similar semantics.
		 For 411 format images, all members should have even values.
		 The minimum cropping unit is this case is 16x16.
		 For 422 format images, the left and right members should
		 have even values, in which case the minimum cropping unit
		 is 16x8. A value supplied as odd which should have been
		 even will be truncated, with 1 subtracted from it.
		
lpstrOutFileName Points to a null-terminated string that names the output
		 JPEG file. It should be NULL if the output is to be
		 returned as a memory object.

lpdwOutStreamLen Returns the size of the output bitstream in bytes if the
		 output is to be returned as a memory object.

lpfnECJ_CallBack Specifies the procedure-instance address of the callback
		 procedure. See ECJ_Decode and ECJ_CallBack.

Returns
=======
If lpstrOutFileName is NULL, a handle to the memory object containing
the output JPEG bitstream is returned upon successful completion.
If the output is to be written to a file, an arbitrary, non-NULL value is
returned. In both cases NULL is returned if the operation fails.

See Also
========
ECJ_Decode, ECJ_CallBack

********************************************************************************

ECJ_CallBack (2.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

int CALLBACK ECJ_CallBack( mMsg, wParam, lParam )

WORD	mMsg;	/* message */
WORD	wParam;	/* first message parameter */
LONG	lParam;	/* second message parameter */

The ECJ_CallBack function is an application-defined callback function that
processes messages sent by ECJ_Decode.

Parameter	Description
--------------------------------------------------------------------------
mMsg		Specifies the message.

		Message		Meaning
		-----------------------------------------------------------
		ECJ_RESOLUTION	Upon decoding the header of the image
				ECJ_Decode returns with the following
				information:

				Parameter   Bits   Meaning
				-------------------------------------------
				lParam	    0-15   Vertical dimension.
				lParam	   15-32   Horizontal dimension.
				wParam	    0-2    Video format.
						   0 = Y;
						   1 = YUV422;
						   2 = YUV411;
						   3 = YUV444;
				wParam	     3     Picture shrunk by half.
				wParam	     4     Picture shrunk by 1/4th.
				wParam	     5     Picture shrunk by 1/8th.

		ECJ_PROGRESS	ECJ_Decode periodically returns control to
				the client with progress information:

				wParam	Stage
				------  ----------------------------------
				0	Pass 1
				1	Creating histogram
				2	Pass 2

				For stages 0 and 2, lParam indicates percentage
				completion.

		ECJ_ERROR	An error has occured. wParam identifies the
				particular error.

				wParam	Error
				---------------------------------------------
				 1	File is not JPEG.
				 2	Can't open file.
				 3	Unexpected EOF.
				 4	Out of memory.
				 5	Unrecognised video format.
				 6	Unexpected scan component.
				 7	Unexpected marker.
				 8	Unexpected RST.
				 9	Unsupported precision.
				10	User abort.

wParam		Bits 8-14 contains the optional 7 bit label passed to the DLL.
		The remaining bits contain message-dependent information.

lParam		More message-dependent information.

Returns
=======
To continue decoding a value of 0 shall be returned.
A return value of -1 instructs ECJ_Decode to abort decoding immediately.

Comments
========
The client does not have to process any of the messages. The simplest
ECJ_CallBack function can simply return 0. A more well behaved application
should take the opportunity to momentarily pass control back to Windows
to achieve non-preemptive multitasking.

See Also
========
ECJ_Decode

********************************************************************************

ECJ_Info (2.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

int ECJ_Info( lpstrfilename, lpX, lpY, lpColourFormat )

LPSTR	lpstrFileName;		/* name of JPEG file */
LPINT	lpX;			/* horizontal size */
LPINT	lpY;			/* vertical size */
LPINT	lpVideoFormat;		/* video format */

ECJ_Info provides some basic information on the specified JPEG file, which
would otherwise be unavailable when the CallBack mechanism is not used. In
particular the video format information is useful in determining the minimum
cropping units.

Parameter	 Description
---------------------------------------------------------------------------
lpstrFileName	 Points to a null-terminated string that names the JPEG file.

lpX		 Pointer to integer which contains the horizontal size of
		 the picture upon successful return.

lpY		 Pointer to integer which contains the vertical size of
		 the picture upon successful return.

lpVideoFormat	 Pointer to integer which contains the chroma-subsampling
		 format of the picture.
		 0 = Y; 1 = YUV422; 2 = YUV411; 3 = YUV444;
Returns
=======
Returns 0 if the function is successful.

See Also
========
ECJ_InfoMem, ECJ_CallBack, ECJ_Crop

********************************************************************************

ECJ_InfoMem (2.x)
--------------------------------------------------------------------------------
int ECJ_Info( hStream, dwStreamLen, lpX, lpY, lpColourFormat )

HGLOBAL	hStream;		/* handle to bitstream in memory */
DWORD	dwStreamLen;		/* size of bitstream in bytes */
LPINT	lpX;			/* horizontal size */
LPINT	lpY;			/* vertical size */
LPINT	lpVideoFormat;		/* video format */

ECJ_InfoMem provides some basic information on the specified JPEG bitstream.
ECJ_InfoMem is essentially the same as ECJ_Info, except that instead of
taking a filename it takes a memory object as input.

Parameter	 Description
---------------------------------------------------------------------------
hStream		 Global handle to memory object containing bitstream.

dwStreamLen	 Size of the bitstream in bytes.

See ECJ_Info for explanations on the rest of the parameters.

Returns
=======
Returns 0 if the function is successful.

See Also
========
ECJ_Info, ECJ_CallBack, ECJ_Crop

