/*******************************************************************************
*                              Openwave Systems.                               *
*                            Device Products Group                             *
*                            Melbourne,  AUSTRALIA                             *
****************************************************************************//**
   @file
   This file declares the API to the Openwave image decoder functions.  This
   header file is a copy of the native browser header, but uses BREW types and
   Doxygen comments.
   Refer to @ref grp_image_decode.

*//*
   REVISION HISTORY:
   Date:       Who:               Email:
      - Details:
--------------------------------------------------------------------------------
   17 Dec 2004 Richard Willis     richard.willis@openwave.com
      - Initial version

*******************************************************************************/
/*******************************************************************************
*                  Copyright (c) Openwave Systems 1995-2004                    *
*                            All rights reserved.                              *
*                                                                              *
*     THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF Openwave Systems Inc.     *
*               The copyright notice above does not evidence any               *
*              actual or intended publication of such source code.             *
*******************************************************************************/

#ifndef _IMAGEDEC_H
#define _IMAGEDEC_H


/*==============================================================================

	INCLUDES

==============================================================================*/


/*==============================================================================

	DEFINES

==============================================================================*/
/**@ingroup grp_image_decode
 This define is returned as #UPICImageId when an image context could not be
 created.
*/
#define kNoImage	0


/**@ingroup grp_image_decode
 This is returned by UPICDecodeFrame() if memory could not be allocated for
 the image decoder.
*/
#define kUPICErrorNoMemory		-1


/**@ingroup grp_image_decode
 This is returned by UPICDecodeFrame() if the image type is not supported.
*/
#define kUPICErrorInvalidImage		-2

											
/*==============================================================================

	TYPES

==============================================================================*/
/**@ingroup grp_image_decode
 This is the handle associated with a each image context.  It is created with a
 call to UPICImageInit().  If set to #kNoImage, indicates that the image context
 could not be created.
*/
typedef void *	UPICImageId;


/**@ingroup grp_image_decode
 This is a callback function pointer to a malloc style memory allocation 
 routine. The routine allocates the requested amount of memory and returns a 
 pointer to that memory. The routine may return NULL if insufficent memory 
 exists to allocate the requested block.
*/
typedef void *	(*UPICAllocFuncPtr)(uint32 lwAllocSize );


/**@ingroup grp_image_decode
 This is a callback function pointer to a free style memory deallocation 
 routine. The routine frees up the memory used by the pointer specified.
*/
typedef void (*UPICFreeFuncPtr)( void *pvMemoryPtr );

/**@ingroup grp_image_decode
 This is the pixel type.  It's either 8 or 16bit depending on the colour depth.
 For BREW, it is set to 16bits.
*/
typedef uint16 ICCOLOR;



/*==============================================================================

	GLOBAL VARIABLE DECLARATIONS

==============================================================================*/


/*==============================================================================

	FUNCTION DECLARATIONS

==============================================================================*/
/*-------------------------------------------------------------------------*//**
@ingroup grp_image_decode
@DESCRIPTION
 The device calls this function to initialize the browser image compositor and 
 pass an encoded image to the browser for decoding.\n\n
 The browser handles image decoding on behalf of the device using memory and 
 memory management functions provided by the device, see #UPICAllocFuncPtr and 
 #UPICFreeFuncPtr. The device must provide pointers to its internal routines 
 for allocating and deallocating memory—for example, its malloc and free 
 routines or equivalents. The browser uses these routines to allocate memory for 
 the decoded image data, then deallocate the memory when the device is done 
 using the image compositor.  The malloc routine must return NULL if there is 
 not enough memory to provide the amount specified by the browser.\n\n
 The calling function must provide callback pointers to its internal routines 
 for memory allocation and deallocation, as well as a pointer to the image data 
 to decode and the byte length of the image data.  The browser creates an image 
 context buffer for the image and returns a opaque handle to that image 
 context.  The browser does not actually decode the first frame of the image 
 until the device calls UPICDecodeFrame(), which the device must do before it 
 can call UPICImageGetPixels() or UPICImageGetTransparencyMask().  However, the 
 device can call UPICImageMeasure() immediately, without calling 
 UPICDecodeFrame() first.  The browser lets the device obtain the dimensions of 
 the image without actually decoding the image. The browser decodes images 
 encoded in PNG, WPNG, GIF, JPEG, 1- and 8-bit BMP, and WBMP formats. The 
 browser decodes all image formats into ICCOLOR image pixel data, in using 
 16-bit color depth.\n\n
 To destroy an image context created by UPICImageInit(), the device should call
 UPICImageDestroy().
@PARAMETERS
 @param[in]  pfpvAllocFunc Callback pointer to memory malloc style function.
 @param[in]  pfvFreeFunc Callback pointer to memory free style function.
 @param[in]  kpbImageData Pointer to image data that will be decoded.
 @param[in]  lwInputSize Amount of image data.
@RETURNS
 A #UPICImageId handle to the image's context or #kNoImage if an error occurred
 (invalid image, unsupported image format).
*//*--------------------------------------------------------------------------*/
UPICImageId UPICImageInit( UPICAllocFuncPtr pfpvAllocFunc, UPICFreeFuncPtr pfvFreeFunc, const unsigned char *kpbImageData, uint32 lwInputSize );


/*-------------------------------------------------------------------------*//**
@ingroup grp_image_decode
@DESCRIPTION
 The device calls this function to obtain the width and height of an image 
 stored in an image context created though UPICImageInit(). The browser may call
 this to obtain the image dimensions, prior to calling UPICDecodeFrame(), to 
 decode the image.\n\n
 The calling function must provide a #UPICImageId handle to an image context and
 pointers to output buffers where the browser is to write the image width and 
 height.
@PARAMETERS
 @param[in]  pvImageId The #UPICImageId handle as returned by UPICImageInit().
 @param[out] piWidth The width of the image in pixels or zero if the image
   could not be measured.
 @param[out] piHeight The height of the image in pixels or zero if the image
   could not be measured.
@RETURNS
 Nil.
*//*--------------------------------------------------------------------------*/
void UPICImageMeasure( UPICImageId pvImageId, int16 *piWidth, int16 *piHeight ); 


/*-------------------------------------------------------------------------*//**
@ingroup grp_image_decode
@DESCRIPTION
 The device calls this function to decode the next frame of an image, static or
 animated, to raw pixel data of type #ICCOLOR. The device must always call this 
 prior to calling UPICImageGetPixels() or UPICImageGetTransparencyMask(), to 
 obtain the pixel data or transparency mask for the frame.\n\n
 The calling function must provide a #UPICImageId handle to an image context and
 specify a boolean value for the oRestart parameter.  The browser decodes the 
 next frame into the image context and returns the duration of the frame, 
 measured in milliseconds.\n\n
 Note that this function updates internal structures of the #UPICImageId image 
 context as it decodes each frame of the animated image.
@PARAMETERS
 @param[in]  pvImageId The #UPICImageId handle as returned by UPICImageInit().
 @param[in]  oRestart TRUE to restart from the first frame or FALSE to decode
   the next frame.
@RETURNS
 The duration of the frame in milliseconds, 0 indicates an infinite duration, or
 no more frames. 
 < 0 indicates failure in image decode:
 - #kUPICErrorNoMemory -- Out of memory error.
 - #kUPICErrorInvalidImage -- Unsupported or corrupt image
 .
@note
 Use the UPICImageGet* routines to access the pixel and mask data for the 
 current frame once it has been decoded.
@warning
 On error, you @b MUST still call UPICImageDestroy.
*//*--------------------------------------------------------------------------*/
int16 UPICDecodeFrame( UPICImageId pvImageId, boolean oRestart );


/*-------------------------------------------------------------------------*//**
@ingroup grp_image_decode
@DESCRIPTION
 The device calls this function to obtain a pointer to the pixel data for the 
 current frame of an image. Before calling this, the device must call 
 UPICDecodeFrame(), to decode the next frame of the image to the image context. 
 For animated images, the device calls UPICDecodeFrame() and this function once 
 per frame.\n\n
 The calling function must provide an #UPICImageId handle to an image context 
 and a pointer for the number of image pixels per row. The browser sets the 
 number of bytes per pixel row and returns a pointer to the image pixel data 
 for the image frame. The device uses pwPelsRowBytes and the image height to 
 determine the amount of data to read from the image context.
 In most cases, the value of pwPelsRowBytes is the same as the width of the 
 image, but the device should not assume that this is always so.
@PARAMETERS
 @param[in]  pvImageId The #UPICImageId handle as returned by UPICImageInit().
 @param[out] pwPelsRowBytes The number of bytes per pixel row.
@RETURNS
 NULL if no frame has yet been decoded, or pointer into the UPICImage's current 
 frame's pixel data.
@note
 pwPelsRowBytes contains the number of bytes per pixel row, normally the same 
 as the width of the image (for 8-bit images) but please do not assume this.
*//*--------------------------------------------------------------------------*/
ICCOLOR *UPICImageGetPixels( UPICImageId pvImageId, uint16 *pwPelsRowBytes );

/*-------------------------------------------------------------------------*//**
@ingroup grp_image_decode
@DESCRIPTION
 The device calls this function to obtain the transparency mask for the current 
 frame of an image. Before calling this, the device must call UPICDecodeFrame(), 
 to decode the next frame of the image. For animated images, the device calls 
 UPICDecodeFrame() and this function once per frame.\n\n
 The calling function provides an #UPICImageId handle to the image context. The 
 browser returns a pointer to the transparency mask data for the image frame. The
 device uses the image dimensions to determine the amount of data to read from 
 the image context.\n\n
 The transparency mask is 1-bit packed, with pixel rows byte-padded.
@PARAMETERS
 @param[in]  pvImageId The #UPICImageId handle as returned by UPICImageInit().
@RETURNS
 NULL if no transparency mask exists (all opaque), or pointer into the
 UPICImage's current frame's transparency mask.
 @warning
 Do @b not deallocate the returned pointer to the transparency mask.
 This will be deallocated during the call to UPICImageDestroy().
*//*--------------------------------------------------------------------------*/
unsigned char *UPICImageGetTransparencyMask( UPICImageId pvImageId );


/*-------------------------------------------------------------------------*//**
@ingroup grp_image_decode
@DESCRIPTION
 Cleans up state and frees all memory associated with a given #UPICImageId
 handle.
@PARAMETERS
 @param[in]  pvImageId The #UPICImageId handle as returned by UPICImageInit().
@RETURNS
 Nil.
*//*--------------------------------------------------------------------------*/
void UPICImageDestroy( UPICImageId pvImageId );


#endif /* _IMAGEDEC_H */

