surfman.h

Lido PXA270平台开发板的最新BSP,包括源代码

/*! 
******************************************************************************
 @file   : sm.h

 @brief  

 @Author Rik Allen

 @date   30/05/2003
 
         <b>Copyright 2003 by Imagination Technologies Limited.</b>\n
         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.

 <b>Description:</b>\n
         This file specifies the public interface to the PowerVR surface manager.
		 This forms a componento if the PowerVR Resource Manager.

 <b>Platform:</b>\n
	     All

 @Version	
	     Alpha 1 

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

 $Log: surfman.h $

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

  --- Revision Logs Removed --- 

 
 *********************************************************************/
#ifndef SM_SURFACE_H_INCLUDED
#define SM_SURFACE_H_INCLUDED


/*! \page SurfMan The Surface Manager 
The surface manager provides an abstraction of a 2d bitmap that can be used by all PowerVR apis.
SMSurfaces can be used to share data between an Mpeg decode process, a 3d render, 
and a display pipeline, amongst other things.

A \ref SMSurfaceHandle is an abstract base class that provides a range of methods 
for accessing a surface and synchronising operations on it.

A ref SMArrayHandle is a collection of SMSurfaceHandle objects that allows 
easier control of multiple buffering.The surface manager has simple \ref Capabilites 
support that allows multiple API's to co-operate to determine the suitability of a 
surface for a particular set of purposes.

The full API for the surface manager is defined in \ref sm.h

*/

/*! \page Capabilites Capability management

The surface manager has a high level view of the surfaces it manages. Only simple aspects 
like the width, height, stride are directly controlled. API specific details like mipmapping 
and clip regions are left to the api's themselves. However a means is provided that 
allows the user to inform a number of API's what a surface to be created will be used 
for, and provides an opportunity to those API's to request extra memory for mipmaps etc. 

To coordinate the use of the surface between multiple api's a capability based system is 
provided, where each api that has an interest in surfaces is required to register a capability 
verification function with the surface manager. When a surface is created, the application 
provides a list of ImgCapabilitys, each of which is a tuple of an identifier for an API, 
and an API defined value indicating what the application intends to use this surface for. 
Each API who's identifier appears in the capabilities list is queried to confirm that the 
surface as described is acceptable. If the API does not accept a set of surface capabilities, 
it acknowledges this in the return value for the caps checker function. The surface manager 
will not proceed to the next checker function in this case, and will report an error to 
the calling function.

<h4>An example.</h4>
On startup, an api registers it's capability checking function. In this example, MGL.

img_surface_register_capabilities('MGL ', mgl_verify_capabilities);

The application would then create a surface with the following ImgCapability array. 
Note that the'MEM ' identifier is declared by the surface manager itself.

  \code
SMCapability  aCaps[] = {
		{'MEM ',BP_CONTIGUOUS | BP_HI_MEMORY | BP_AVOID_2K_BOUNDARY },
		{'MGL ', MGL_TEXTURE},
		{'MGL ', MGL_MIPMAP_LEVELS_3},
		{'MGL ', MGL_PIXEL_FORMAT_R4G4B4A4);


sm_surface_simple_create(&hSurface, 
						ui32Width,  // in pixels
						ui32Height, // in pixels
						ui32Stride, // in bytes
						ePixelFormat,
						eMemoryFlags,
						4
						*aCaps
					  );
 \endcode

Internally, the surface manager would then call the MGL provided capability checking function as follows