/*!****************************************************************************
@File			services.h

@Title			Services API Header

@Author			Imagination Technologies

@date   		01/08/2003
 
@Copyright     	Copyright 2003-2004 by Imagination Technologies Limited.
                All rights reserved. No part of this software, either
                material or conceptual may be copied or distributed,
                transmitted, transcribed, stored in a retrieval system
                or translated into any human or computer language in any
                form by any means, electronic, mechanical, manual or
                other-wise, or disclosed to third parties without the
                express written permission of Imagination Technologies
                Limited, Unit 8, HomePark Industrial Estate,
                King's Langley, Hertfordshire, WD4 8LZ, U.K.

@Platform		cross platform / environment

@Description	exported services API details

@DoxygenVer		

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

/******************************************************************************
Modifications :-

$Log: services.h $
*****************************************************************************/

#if !defined (__SERVICES_H__)
#define __SERVICES_H__

#if defined (__cplusplus)
extern "C" {
#endif

#include "img_defs.h"


/* The comment below is the front page for code-generated doxygen documentation */
/*!
 *****************************************************************************
 @mainpage
 This document details the APIs and implementation of the Consumer Services.
 It is intended to be used in conjunction with the Consumer Services
 Software Architectural Specification and the Consumer Services Software 
 Functional Specification.
 *****************************************************************************/

/*****************************************************************************
 * 	#defines
 *****************************************************************************/

/*
 * queued command types for services managed devices
 */
#define PVRSRV_CMD_ID_BLT				1	/*!< 2D Blit command */
#define PVRSRV_CMD_ID_FLIP				2	/*!< display flip command */
#define PVRSRV_CMD_ID_RENDER			3	/*!< 3d render command */
#define PVRSRV_CMD_ID_LOCK				4	/*!< lock command - based on a synchronisation object */
#define PVRSRV_CMD_ID_UPDATE			5	/*!< Screen update command - causes any screen in single shot mode to be updated */
#define PVRSRV_CMD_ID_FLIP_OVERLAY		6	/*!< display flip-overlay command */
#define PVRSRV_CMD_ID_RENDER_BLIT		7	/*!< MBX render blit command */
#define PVRSRV_CMD_ID_OVL_RENDER_BLIT	8	/*!< MBX render blit command */

/*
 * other command specific defines
 */
#define PVRSRV_MAX_BLT_SRC		3	/*!< The largest number of source sync objects that can be associated with
										 a blit command. Allows for dst, src , pattern, and mask */										
#define PVRSRV_MAX_RENDER_SRC	10	/*!< Max number of sync objects that can be associated with a 3d render. 
										 These would be used for dynamic textures etc - textures that do not change need 
										 not be listed */
#define PVRSRV_MAX_CMD_SIZE		1024/*!< max size in bytes of a command */


#define PVRSRV_MAX_DEVICES		16	/*!< Largest supported number of devices on the system */


/*
 *	Flags associated with memory allocation
 */ 
#define PVRSRV_MEMFLG_RENDERABLE		(1<<0)	/*!< Allocate memory suitable for a 3d render */
#define PVRSRV_MEMFLG_TEXTURE			(1<<1)  /*!< Allocate memory suitable for a 3d texture */
#define PVRSRV_MEMFLG_ZBUFFER			(1<<2)	/*!< Allocate memory suitable for a 3d depth buffer */
#define PVRSRV_MEMFLG_CONTIGIOUS		(1<<3)	/*!< The buffer should not be fragmented - suitable for display on a non MMU device */
#define PVRSRV_MEMFLG_ALTERNATE_HEAP	(1<<4)	/*!< Allocate the memory from a system defined "alternative" heap - eg external */
#define PVRSRV_MEMFLG_FLIPPABLE     	(1<<5)	/*!< This allocation is a flippable surface */
#define PVRSRV_MEMFLG_SAVERESTORE     	(1<<6)	/*!< This allocation should be saved/restored */

/*
 *	Flags associated with memory allocation status
 */
#define PVRSRV_MEMFLG_MEMORY_NOT_AVAILABLE	(1<<7)	/*!< Memory at which this meminfo was pointing is gone due to powerdown event */

#define PVRSRV_MEMFLG_NO_RESMAN		(IMG_UINT32)(1<<31)	/*!< Do not resource manage this allocation */

/*
 *	How much context we lose on a (power) mode change
 */
#define PVRSRV_NO_CONTEXT_LOSS					0		/*!< Do not lose state on power down */
#define PVRSRV_SEVERE_LOSS_OF_CONTEXT			1		/*!< lose state on power down */
#define PVRSRV_PRE_STATE_CHANGE_MASK			0x80	/*!< power state change mask */


/*
 * Device cookie defines 
 */
#define PVRSRV_DEFAULT_DEV_COOKIE			(1)	 /*!< default device cookie */

/*
 * Flags for PVRSRVAddRenderTarget
 */
#define PVRSRV_ADDRENDERTARGET_AAX		(1 << 0)	/*!< super sample in X */
#define PVRSRV_ADDRENDERTARGET_AAY		(1 << 1)	/*!< super sample in Y */

/*
 * Resman process id define 
 */
#define PVRSRVRESMAN_PROCESSID_FIND			(0xffffffff) /*!< Resman process id define */

/*!
 * Does MBX adhere to new standards on enable and disable?
 */
#define PVRSRV_MBX_COREFLAG_NEW_RESET	0x00000001

/*****************************************************************************
 * Enums
 *****************************************************************************/


/*!
 *****************************************************************************
 * Error values
 *****************************************************************************/
typedef enum _PVRSRV_ERROR_
{
	PVRSRV_OK							=  0,
	PVRSRV_ERROR_GENERIC				=  1,
	PVRSRV_ERROR_OUT_OF_MEMORY			=  2,
	PVRSRV_ERROR_TOO_MANY_BUFFERS		=  3,
	PVRSRV_ERROR_SYMBOL_NOT_FOUND		=  4,
	PVRSRV_ERROR_OUT_OF_HSPACE			=  5,
	PVRSRV_ERROR_INVALID_PARAMS			=  6,
	PVRSRV_ERROR_TILE_MAP_FAILED		=  7,
	PVRSRV_ERROR_INIT_FAILURE			=  8,
	PVRSRV_ERROR_CANT_REGISTER_CALLBACK =  9,
	PVRSRV_ERROR_INVALID_DEVICE			= 10,
	PVRSRV_ERROR_NOT_OWNER				= 11,
	PVRSRV_ERROR_BAD_MAPPING			= 12,
	PVRSRV_ERROR_TIMEOUT				= 13,
	PVRSRV_ERROR_NO_PRIMARY				= 14,
	PVRSRV_ERROR_FLIP_CHAIN_EXISTS		= 15,
	PVRSRV_ERROR_CANNOT_ACQUIRE_SYSDATA = 16,
	PVRSRV_ERROR_SCENE_INVALID			= 17,
	PVRSRV_ERROR_STREAM_ERROR			= 18,
	PVRSRV_ERROR_NO_MUTEX               = 19,
	PVRSRV_ERROR_INVALID_INTERRUPT      = 20,

	PVRSRV_ERROR_FORCE_I32 = 0x7fffffff

} PVRSRV_ERROR;



/*!
 *****************************************************************************
 * List of known device types.
 *****************************************************************************/
typedef enum _PVRSRV_DEVICE_TYPE_
{
	PVRSRV_DEVICE_TYPE_UNKNOWN			= 0 ,
	PVRSRV_DEVICE_TYPE_MBX1				= 1 ,
	PVRSRV_DEVICE_TYPE_MBX1_LITE		= 2 ,

	PVRSRV_DEVICE_TYPE_M24VA			= 3,

	PVRSRV_DEVICE_TYPE_JDISPLAY			= 4,
	PVRSRV_DEVICE_TYPE_CRTC				= 5,
	PVRSRV_DEVICE_TYPE_PDP				= 6,

	PVRSRV_DEVICE_TYPE_DMAC				= 7,

	PVRSRV_DEVICE_TYPE_RENESAS_LCD		= 8,
	PVRSRV_DEVICE_TYPE_CLCDC			= 9,

	PVRSRV_DEVICE_TYPE_FORCE_I32		= 0x7fffffff

} PVRSRV_DEVICE_TYPE;

/*!
 *****************************************************************************
 * List of known device classes.
 *****************************************************************************/
typedef enum _PVRSRV_DEVICE_CLASS_
{
	PVRSRV_DEVICE_CLASS_3D				= 0 ,
	PVRSRV_DEVICE_CLASS_DISPLAY			= 1 ,
	PVRSRV_DEVICE_CLASS_MPEG			= 2 ,

	PVRSRV_DEVICE_CLASS_FORCE_I32 		= 0x7fffffff

} PVRSRV_DEVICE_CLASS;


/*!
 *****************************************************************************
 *	States for power management. Used by WinCE
 *****************************************************************************/ 
typedef enum _PVRSRV_POWER_STATE_
{
	PVRSRV_POWER_STATE_D0				= 0,	/*!< On, */
	PVRSRV_POWER_STATE_D1				= 1,	/*!< User Idle */
	PVRSRV_POWER_STATE_D2				= 2,	/*!< System Idle */
	PVRSRV_POWER_STATE_D3				= 3,	/*!< Suspend */
	PVRSRV_POWER_STATE_FORCE_I32 = 0x7fffffff

} PVR_POWER_STATE, *PPVR_POWER_STATE;


/*!
 *****************************************************************************
 *	Types (and meaningful combinations of) slaveport 
 *****************************************************************************/
typedef enum _PVRSRV_SLAVEPORT_TYPE_	
{
	PVRSRV_SLAVEPORT_3D	= 0,			/* Includes TA TERM*/
	PVRSRV_SLAVEPORT_2D	= 1,
	PVRSRV_SLAVEPORT_3D_DATA	=2,
	PVRSRV_SLAVEPORT_3D_CTL		=3,

	PVRSRV_SLAVEPORT_FORCE_I32 = 0x7fffffff

} PVRSRV_SLAVEPORT_TYPE;

/*! 
 *****************************************************************************
 * Enumeration of all possible pixel types. 
 *****************************************************************************/
typedef enum _PVRSRV_PIXEL_FORMAT_ {
	PVRSRV_PIXEL_FORMAT_RGB565			=  1,
	PVRSRV_PIXEL_FORMAT_RGB555			=  2,
	PVRSRV_PIXEL_FORMAT_RGB888			=  3,
	PVRSRV_PIXEL_FORMAT_BGR888			=  4,
	PVRSRV_PIXEL_FORMAT_YUV420			=  5,
	PVRSRV_PIXEL_FORMAT_YUV444			=  6,
	PVRSRV_PIXEL_FORMAT_VUY444			=  7,
	PVRSRV_PIXEL_FORMAT_GREY_SCALE		=  8,
	PVRSRV_PIXEL_FORMAT_YUYV			=  9,
	PVRSRV_PIXEL_FORMAT_YVYU			= 10,
	PVRSRV_PIXEL_FORMAT_UYVY			= 11, 
	PVRSRV_PIXEL_FORMAT_VYUY			= 12,
	PVRSRV_PIXEL_FORMAT_PAL12			= 13,
	PVRSRV_PIXEL_FORMAT_PAL8			= 14,
	PVRSRV_PIXEL_FORMAT_PAL4			= 15,
	PVRSRV_PIXEL_FORMAT_PAL2			= 16,
	PVRSRV_PIXEL_FORMAT_PAL1			= 17,
	PVRSRV_PIXEL_FORMAT_ARGB1555		= 18,
	PVRSRV_PIXEL_FORMAT_ARGB4444		= 19, 
	PVRSRV_PIXEL_FORMAT_ARGB8888		= 20,
	PVRSRV_PIXEL_FORMAT_ABGR8888		= 21,
	PVRSRV_PIXEL_FORMAT_YV12			= 22,
	PVRSRV_PIXEL_FORMAT_I420			= 23,
	PVRSRV_PIXEL_FORMAT_DXT1			= 24,
	
	PVRSRV_PIXEL_FORMAT_FORCE_I32 = 0x7fffffff,
} PVRSRV_PIXEL_FORMAT;

/*!
 *****************************************************************************
 *	User Module type
 *****************************************************************************/
typedef enum
{
	IMG_OPENGLES = 0x00000001 ,
	IMG_D3DM
}IMG_MODULE_ID;

/*!
 *****************************************************************************
 *	IMG data types
 *****************************************************************************/
typedef enum
{
	IMG_STRING_TYPE		= 1,
	IMG_FLOAT_TYPE		,
	IMG_UINT_TYPE		,
	IMG_INT_TYPE		,
	IMG_FLAG_TYPE
}IMG_DATA_TYPE;

/*****************************************************************************
 * Forwards references for some structures..
 *****************************************************************************/

typedef struct _RESMAN_ITEM_			*PRESMAN_ITEM;		/*!< forward reference */
typedef struct _LASTOP_BLOCK_			*PLASTOP_BLOCK;		/*!< forward reference */
typedef struct _PVRSRV_DEV_INFO_		*PPVRSRV_DEV_INFO;	/*!< forward reference */
typedef struct _PVRSRV_DEV_DATA_		*PPVRSRV_DEV_DATA;	/*!< forward reference */

#ifdef SUPPORT_POWER_STATE
typedef void (IMG_CALLCONV *PSTATE_CALLBACK) (PPVRSRV_DEV_INFO, PVR_POWER_STATE, IMG_UINT32, IMG_UINT32);
/*!< Power state callback function pointer */
#endif

/*!
 *****************************************************************************
 *	Power state callbacks
 *****************************************************************************/

#ifdef SUPPORT_POWER_STATE

typedef struct _STATE_REGISTER_
{
    PSTATE_CALLBACK         pfnCallback;
    PPVRSRV_DEV_INFO        psDevInfo;
    IMG_UINT32              ui32Context;
} STATE_REGISTER, *PSTATE_REGISTER;

#endif

/*****************************************************************************
 * Definitions for some implementation handles..
 *****************************************************************************/
typedef struct _RENDERSYNCS*			RENDERSYNCS_HANDLE;			/*!< render sync handle */
typedef struct _BLTSYNCS*				BLTSYNCS_HANDLE;			/*!< blit sync handle */
typedef struct _VSYNC_FLIP_CMD_INFO*	VSYNC_FLIP_CMD_INFO_HANDLE;	/*!< flip sync handle */