// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __SURFACEUPDATECLIENT_H__

#define __SURFACEUPDATECLIENT_H__

#include <e32std.h>

#include <graphics/suerror.h>

#ifdef TEST_SURFACE_UPDATE

#include "surfaceupdate.h"

#include "surfaceupdatetest.h"

#endif

class TSurfaceId;

const TInt KDefaultMessageSlot = 6;

typedef TPckgBuf<TUint32> TTimeStamp;

/**

The RSurfaceUpdateSession class is intended to be used by surface update control flow.

The class implements an interface between the Compositor and clients. It allows a client to 

inform the Compositor when a surface has been modified and to receive notification when 

its buffer becomes available and/or displayed. 

*/

class RSurfaceUpdateSession : public RSessionBase

	{

public:

	IMPORT_C RSurfaceUpdateSession();

	/**

	Connect to the server using given number of message slots.

	@param aMessageSlots The number of message slots available to this session.  

	This parameter is defined in RSessionBase specification; it signifies the maximum number 

	of asynchronous outstanding requests to the server.  

	SubmitUpdate commands could contain up to three asynchronous requests to the server, 

	each corresponds to a different type of notification. 

	@see RSessionBase

	@pre The surface update server is started up

	@post Connection to the server has been established. 

	@return KErrNone if successful. 

	@return KErrAlreadyExists if the session has already been established.

	@return KErrArgument if arguments don’t lie within expected range. 

	@return KErrNotFound if the server is not in operation, otherwise one of the 

	    system-wide error codes.

	*/

	IMPORT_C TInt Connect(TInt aMessageSlots = KDefaultMessageSlot);

	/**

	Close the session to the server. 

	@pre Outstanding notification requests (if any) are cancelled.

	@post The session is disconnected.

	*/

	IMPORT_C void Close();	

	/**

	Send update message to the server. All notification requests will also be submitted at 

	this stage. 

	This is referring to when notifications are requested before the update request.

	<p>The GCE may collapse a few requests into one. 

	If a few requests with different buffer numbers specified for the same surface have 

	been submitted at specific composition cycle, only last such request will have effect. 

	<p>Clients can send a global submit update which will be broadcast by the SUS to all 

	backends presented in the system. For a global update, to all screens, 

	the pre-defined constant KAllScreens needs to be passed as the screen parameter 

	to SubmitUpdate. 

	Note that once a Client has begun issuing SubmitUpdate with either KAllScreens or a 

	specific screen, then only that type of screen can be used thereafter for that 

	Surface Update Session, i.e. the client cannot have a mix of SubmitUpdate with 

	KAllScreens and specific screens.

	@see RSurfaceUpdateSession::NotifyWhenAvailable

	@see RSurfaceUpdateSession::NotifyWhenDisplayed 

	@see RSurfaceUpdateSession::NotifyWhenDisplayedXTimes  

	@param aScreen Screen number. KAllScreens is the only allowed parameter. 

	@param aSurfaceId Secure 128-bit surface unique  identifier, which fully specified the 

	    surface. Surface ID must be assigned and registered with the GCE.

	@param aBuffer Current buffer for composition. Varies from 0 to N-1, where N is the 

	    total number of buffers in the surface.

	@param aRegion The region requiring update, if this is NULL or empty, the whole 

	    surface will be used for composition. The function doesn’t take ownership of 

	    this parameter.

	@pre The surface session must be established to the server.

	@post The GCE will trigger composition to use this region at the next composition cycle. 

	@return KErrNone if a message has been transferred to the server successfully. 

	@return KErrArgument if arguments don’t lie within expected range.

	@return KErrBackendNotAvailable if backend for specified screen hasn’t been registered 

	    with the server.

	@return KErrNotSupported if global and per-screen update are mixed within the same session.

	@return KErrNoMemory if the memory is not enough to fulfill the request, 

	    otherwise one of the system-wide error codes.

	Will panic if applied on disconnected session.

	*/

	IMPORT_C TInt SubmitUpdate(TInt aScreen, const TSurfaceId& aSurfaceId, TInt aBuffer, 

						const TRegion* aDirtyRegion = NULL);

	/**

	The message signals the client that the buffer associated with the notifier is available 

	for further updates.

	<p>For performance reasons, the GCE uses the buffer sent by the client for composition 

	directly rather than composing with a copy of the buffer. 

	This means that, potentially, a client could be rendering to a buffer which is currently 

	being used for composition, leading to artefacts and possible tearing.

	Depending on whether the surface is single or multi-buffered, there is some difference 

	in behaviour:  

	<li>In the case of single-buffered surfaces, the GCE will not wait for the next 

	submit update and will complete the request after the composition. </li>

	<li>In case of multi-buffered surfaces, the GCE can postpone with the issuing the notification 

	to the client even after the composition with the specified surface buffer has already happened, 

	and issues the request when the client changes the active buffer, i.e. submits another 

	request for update with different buffer. This will help the GCE to keep the active buffer in a 

	valid state should another composition required.</li> 

	<p>This notification enables a client to, if desired, be able to perform artefact free 

	rendering using this notification in conjunction with a multi-buffered surface.

	<p>Note that since the compositor can delay to issue request complete for multi-buffered 

	surface until the change of the active buffer occurs, the completion of a particular 

	notifier may not relate to the buffer to which it is intuitively associated. 

	<p>Only the last call of this function before SubmitUpdate command takes place will have 

	effect, i.e. the following call will override the previous one.

	This request will only be associated with the following single call of the SubmitUpdate.

	<p>When a SubmitUpdate has been broadcast to all available screen, i.e. KAllScreens was 

	supplied as a screen number, for multi-buffered surfaces, the notification will be completed 

	when the surface buffer has been released by all displays it is being shown on. 

	For single-buffered surfaces, notification will be completed when all displays have read 

	the buffer once.

	@param aStatus Reference to the request status object.

	@see RSurfaceUpdateSession::SubmitUpdate

	@pre The surface session must be established to the server.

	@post This request for the consumption notification event will be transferred to the GCE 

        at next SubmitUpdate command.  

	@return KErrNone if consumption has succeeded, the request completed aStatus will 

	    contain this code.  

	@return KErrOverflow if the GCE drops the frame for composition. That could happen 

	    if the GCE can’t cope with the current composition rate or the new request arrives 

	    while the current is still in a progress.

	    The buffer overflow error can only happen with double buffering:

	    <li>If notification is not being used</li>

	    <li>If notification is not being used correctly as the client is not waiting for 

	    notification to complete before sending a further buffer.</li>

	    If an application such as video is using three (or more) buffers, this error can occur. 

	    For instance, the video may be producing frames at a fixed rate which is faster than 

	    the GCE can cope with, and in this case frames will be “lost”, but the notification 

	    mechanism will still operate correctly.

	@return KErrBackendNotAvailable if backend for specified screen hasn’t been registered 

	    with the server.

	@return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range.

	@return KErrCancel if notification has been cancelled. It could happen, for instance, 

	    if CancelUpdateNotification is called before the request is completed.

	@return KErrServerBusy if the number of outstanding requests has exceeded specified 

	    value (see   RSurfaceUpdateSession::Connect for details).

	@return KErrNotReady if the environment is in invalid state (for instance, the Surface 

	    Update Server has not been launched or the session is disconnected).

	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.

	@return KErrNotVisible if the surface specified in SubmitUpdate is not visible. 

	    This could happen if there is no layer associated with the surface or no active 

	    composition scene. 

	    Note, the absence of this error code does not guarantee that the surface 

	    is visible. For example, if the surface is behind another surface that has alpha blending

	    enabled the compositor will not do a pixel level comparison to determine surface visibility.

	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.     

	@return KErrNotSupported if global and per-screen update are mixed within the same session.

	@return KErrNoMemory if the memory is not enough to fulfil the request, any other 

	    system error codes.

	Will panic if applied on disconnected session.

	*/

	IMPORT_C void NotifyWhenAvailable(TRequestStatus& aStatus); 

	/**

	Ask the server to notify when the surface buffer which will be specified in the next 

	update request has been displayed for the first time. 

	The notification will also include exact time of the event as it is supplied by the 

	User::FastCounter(). 

	Only the last call of this function before SubmitUpdate command takes place will 

	have effect, i.e. the following call will override the previous one. 

	@param aStatus Reference to the request status object.

	@param aTimeStamp Reference to the timestamp of the display notification event, 

	   packed into the modified buffer descriptor. 

	   Will only be valid if aStatus is equal to KErrNone. 

	@see RSurfaceUpdateSession::SubmitUpdate

	@pre The surface session must be established to the server.

	@post This request for the display notification event will be transferred to the GCE 

	   at next SubmitUpdate command.

	@return KErrNone if the surface has been displayed successfully, when request 

	    completed aStatus will contain this error code.

	@return KErrOverflow if the updated buffer was not displayed because it was 

	    superseded by a further update on the same surface. 

	@return KErrBackendNotAvailable if backend for specified screen hasn’t been 

	    registered with the server.

	@return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range.

	@return KErrCancel if notification has been cancelled. It could happen, for instance, 

	    if CancelUpdateNotification is called before the request is completed.

	@return KErrServerBusy if the number of outstanding requests has exceeded specified 

	    value (@see RSurfaceUpdateSession::Connect for details).

	@return KErrNotReady if the environment is in invalid state (for instance, the 

	    Surface Update Server has not been launched or session is disconnected).

	@return KErrNotVisible if the surface specified in SubmitUpdate is not visible. 

	    This could happen if there is no layer associated with the surface or no active 

	    composition scene.

	    For global update it signifies that the surface is not visible for any screen. 

	    Note, the absence of this error code does not guarantee that the surface is visible. 

	    For example, if the surface is behind another surface that has alpha blending

	    enabled the compositor will not do a pixel level comparison to determine surface visibility.

	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.

	@return KErrNotSupported if global and per-screen update are mixed within the same session.

	@return ErrNoMemory if the memory is not enough to fulfill the request, otherwise any 

	    other system error codes. 

	Will panic if applied on disconnected session.

	*/

	IMPORT_C void NotifyWhenDisplayed(TRequestStatus& aStatus, TTimeStamp& aTimeStamp);

	/**

	Ask the server to notify when the surface buffer which will 

	be specified in the next update request has been displayed for the X times. 

	<p>Only the last call of this function before SubmitUpdate command takes place 

	will have effect, i.e. the following call will override the previous one.

	<p>In case of the global update the notification will always be aligned with the master 

	display. The SUS will send notification to client when the surface has been displayed on a 

	master display for the X times or if there is no master display for that surface. 

	If the master becomes invisible while the request is still in a progress it will be 

	reassigned to the next visible display with highest priority.

	<p>This request will only be associated with the following single call of the SubmitUpdate.

	@param aCount Number of times the surface is displayed  before the request is completed. 

	    Varies from 1 and greater. 

	@param aStatus Reference to the request status object.

	@pre The surface session must be established to the server.

	@post This request for the display notification event will be transferred to the GCE at 

	    next SubmitUpdate command.  

	@return KErrNone if the surface has been displayed successfully for specified numbers 

	    of times, when request completed aStatus will contain this error code.

	@return KErrOverflow if the updated buffer did not remain on-screen for the specified 

	    number of display refreshes because it was superseded by a further update on the 

	    same surface.

	@return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range.

	@return KErrBackendNotAvailable if backend for specified screen hasn’t been registered 

	    with the server.

	@return KErrCancel if notification has been cancelled. It could happen, for instance, 

	    if CancelUpdateNotification is called before the request is completed.

	@return KErrServerBusy if the number of outstanding requests has exceeded 

	    specified value (@see RSurfaceUpdateSession::Connect for details).

	@return KErrNotReady if the environment is in invalid state (for instance, the 

	    Surface Update Server has not been launched or session is disconnected).

	@return KErrNotVisible if the surface specified in SubmitUpdate is not visible. 

	    This could happen if there is no layer associated with the surface or no active 

	    composition scene. 

	    For global update it signifies that the surface is not visible for any screen. 

	    Note, the absence of this error code does not guarantee that the surface is visible. 

	    For example, if the surface is behind another surface that has alpha blending

	    enabled the compositor will not do a pixel level comparison to determine surface visibility.

	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.

	@return KErrNotSupported if global and per-screen update are mixed within the same session.

	@return KErrNoMemory if the memory is not enough to fulfill the request, otherwise 

	    any other system error codes. 

	Will panic if applied on disconnected session.

	*/

	IMPORT_C void NotifyWhenDisplayedXTimes(TInt aCount, TRequestStatus&  aStatus);

	/**

	Cancel all outstanding requests for notification. 

	The function doesn't cancel the submit update requests themselves.

	@pre The surface session must be established to the server.

	@post The server will issue request complete immediately for all outstanding requests 

	    related to particular session.

	Will panic if applied on disconnected session.

	*/

	IMPORT_C void CancelAllUpdateNotifications();

protected:

    /**

    Allow to retrieve the version number.

	@return client version number

    */

	TVersion Version() const;

private:	

	void IssueRequestComplete(TInt aErr);

private:

	TRequestStatus *iStatusAvailable;

	TRequestStatus *iStatusDisplayed;

	TRequestStatus *iStatusDisplayedXTimes;

	TTimeStamp* iTimeStamp;

	TInt iCount;

	};

#endif