sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @internalTechnology
sl@0:  @prototype
sl@0: */
sl@0: 
sl@0: #ifndef SGIMAGE_SW_H
sl@0: #define SGIMAGE_SW_H
sl@0: 
sl@0: #include <e32def.h>
sl@0: 
sl@0: 
sl@0: /**
sl@0: @internalTechnology
sl@0: @prototype
sl@0: 
sl@0: This interface allows direct access to the pixel data of an image from user-side
sl@0: code. It is intended for use by software implementations of functions in the
sl@0: Graphics subsystem.
sl@0: 
sl@0: This interface is only supported if the image is or can be stored in system memory.
sl@0: This is always the case on platforms without hardware acceleration and also on
sl@0: platforms with Unified Memory Architecture (UMA) hardware accelerators.
sl@0: */
sl@0: class MSgImage_Sw
sl@0: 	{
sl@0: public:
sl@0: 	enum { EInterfaceUid = 0x102858F0 };
sl@0: 	/**
sl@0: 	@internalTechnology
sl@0: 	@prototype
sl@0: 
sl@0: 	Retrieves the base address of the pixel data in system memory.
sl@0: 
sl@0: 	@pre In builds with SYMBIAN_GRAPHICS_AUTOFLUSH_CACHE, the image has been prepared
sl@0: 	     for CPU access to its pixel data by a previous call to BeginDataAccess().
sl@0: 	@post None.
sl@0: 	@return The base address of the pixel data in system memory.
sl@0: 	@panic SGRES-ADAPTER 4 in debug builds with SYMBIAN_GRAPHICS_AUTOFLUSH_CACHE,
sl@0: 	       if the image has not been prepared for CPU access to its pixel data by
sl@0: 	       a previous call to BeginDataAccess().
sl@0: 	*/
sl@0: 	virtual TAny* DataAddress() const = 0;
sl@0: 	/**
sl@0: 	@internalTechnology
sl@0: 	@prototype
sl@0: 
sl@0: 	Retrieves the number of bytes between rows of the pixel data in system memory.
sl@0: 
sl@0: 	@pre None.
sl@0: 	@post None.
sl@0: 	@return The number of bytes between rows of the pixel data in system memory.
sl@0: 	*/
sl@0: 	virtual TInt DataStride() const = 0;
sl@0: 	/**
sl@0: 	@internalTechnology
sl@0: 	@prototype
sl@0: 
sl@0: 	Marks the beginning of CPU access to the pixel data. This function must be
sl@0: 	called before DataAddress() in builds with SYMBIAN_GRAPHICS_AUTOFLUSH_CACHE
sl@0: 	and prepares the image for CPU access to its pixel data in system memory. Calls
sl@0: 	to BeginDataAccess() must be coupled with subsequent calls to EndDataAccess().
sl@0: 
sl@0: 	@pre aCpuAccess is not ESgCpuAccessNone.
sl@0: 	@pre The image has not been mapped for CPU access to its pixel data by a
sl@0: 	     call to RSgImage::MapReadOnly(), RSgImage::MapWriteOnly() or
sl@0: 	     RSgImage::MapReadWrite().
sl@0: 	@pre The image has not been prepared for CPU access to its pixel data by a
sl@0: 	     call to BeginDataAccess().
sl@0: 	@post The image is prepared for CPU access to its pixel data.
sl@0: 	@param aCpuAccess Whether the pixel data is going to be only read, only
sl@0: 	       written or read and written by the CPU until the corresponding call
sl@0: 	       to EndDataAccess().
sl@0: 	@return KErrNone if successful.
sl@0: 	@return KErrArgument if aCpuAccess is ESgCpuAccessNone.
sl@0: 	@return KErrInUse if the image was already mapped or prepared for CPU access
sl@0: 	        to its pixel data.
sl@0: 	@return KErrNoMemory if there is not enough system memory.
sl@0: 	*/
sl@0: 	virtual TInt BeginDataAccess(TSgCpuAccess aCpuAccess) = 0;
sl@0: 	/**
sl@0: 	@internalTechnology
sl@0: 	@prototype
sl@0: 
sl@0: 	Marks the end of CPU access to the pixel data. This function must be called
sl@0: 	when finished using the values returned by DataAddress() in builds with
sl@0: 	SYMBIAN_GRAPHICS_AUTOFLUSH_CACHE and ensures that, if the CPU has modified
sl@0: 	the pixel data, any subsequent usage of the image by the GPU will reflect
sl@0: 	its new state. Calls to EndDataAccess() must correspond to prior calls to
sl@0: 	BeginDataAccess().
sl@0: 
sl@0: 	@pre The image has been prepared for CPU access to its pixel data by a
sl@0: 	     successful call to BeginDataAccess().
sl@0: 	@post The image is no longer prepared for CPU access to its pixel data.
sl@0: 	@return KErrNone if successful.
sl@0: 	@return KErrGeneral if the image had not been prepared for CPU access to its
sl@0: 	        pixel data by a successful call to BeginDataAccess().
sl@0: 	*/
sl@0: 	virtual TInt EndDataAccess() = 0;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: #endif // SGIMAGE_SW_H