// Copyright (c) 2010 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:

// Interface to find out when a particular content update 

// for a given surface has been delivered to the compositor

// and will be used in future compositions involving that 

// surface.

// 

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef __CONTENTREADYFORCOMPOSITION_H__

#define __CONTENTREADYFORCOMPOSITION_H__

#include <e32std.h>

#include <graphics/surface.h>

/**

MContentReadyForComposition is an interface to find out when a 

particular content update for a given surface has been delivered to

the compositor and will be used in future compositions involving that 

surface.

The compositor maintains a content update count for each registered 

surface that determines when content ready notifications will be 

completed. The content update count is internally incremented by the 

compositor every time it receives a valid content update for a 

registered surface. Frames may be skipped if the client submits 

content updates too fast, meaning that not every update is displayed 

on screen. The first valid content update sets the content update 

count to one. Updates sent before the surface is registered do not 

affect the content update count. Content ready notifications for 

aContentUpdate = 1 will only be successfully completed after at least

one content update has been received.

*/

class MContentReadyForComposition

    {

public:

    enum

        {

        KUidContentReadyForComposition = 0x2002E6D5,

        ETypeId = KUidContentReadyForComposition

        };

public:

    /**

    Requests a notification when a particular content update for a 

    given surface has been delivered to the compositor. Further, 

    notification implies that this newest content will be used in 

    future compositions until such time that newer content is 

    available.

    @param  aSurface        Id of the surface for which the

                            notification is required.

    @param  aNotifyReady    Request status that is signaled on the 

                            calling thread.

    @param  aContentUpdate  Content update number for which 

                            notification is required.

    @note   aContentUpdate is one-based. Content update one 

            corresponds to the first content submitted to the 

            compositor for a given surface.

    @note   If aContentUpdate is less than or equal to the current 

            content that the compositor uses for aSurface during 

            composition, aNotifyReady is completed with KErrNone 

            without delay. Else aNotifyReady is completed with 

            KErrNone when the compositor has received content update

            number aContentUpdate for the surface.

    @note   aNotifyReady is set to KRequestPending during the call

            to NotifyContentReady() and remains set to this value 

            until the request is completed with the appropriate 

            return code. The client must wait for this asynchronous 

            completion before attempting to read the return value.

    @note   If the registration count for aSurface becomes zero and 

            the surface is no longer in use in either the committed 

            or uncommitted scene while a notification request is 

            outstanding, the notification is completed with KErrAbort,

            without delay soon after the surface is unregistered.

    @note   Due to the 64-bit precision of aContentUpdate, the 

            probability of wrap around is considered slim and 

            therefore ignored. If wrap around does occur, behaviour of

            the API is undefined.

    @pre    aSurface is registered.

    @pre    aContentUpdate >= 1.

    @pre    There is no outstanding notification request for aSurface. 

    @error  If aSurface is not registered, aNotifyReady is completed

            with KErrArgument without delay.

    @error  If aContentUpdate == 0, aNotifyReady is completed with 

            KErrArgument without delay.

    @error  If there is an outstanding notification request for 

            aSurface, aNotifyReady is completed with KErrInUse without

            delay.

    @post   aNotifyReady will be signaled on the calling thread

            according to the above criteria.

    */

    virtual void NotifyContentReady(const TSurfaceId& aSurface, TUint64 aContentUpdate, TRequestStatus& aNotifyReady) = 0;

    /**

    Cancels a notification request made previously with 

    MContentReadyForComposition::NotifyContentReady() for a specific

    surface.

    @see    MContentReadyForComposition::NotifyContentReady().

    @param  aSurface        Id of the surface for which the 

                            notification request will be cancelled.

    @pre    aSurface is registered. 

    @error  If aSurface is not registered, this function is a noop.

    @post   If there is an outstanding notification request for 

            aSurface at the time of the call, it is completed with 

            KErrCancel without delay on the thread that originally 

            called NotifyContentReady() to make the request. If there

            is no outstanding notification request, this function is 

            a noop.

    @note   Completion of an outstanding request with KErrCancel

            must not rely on the calling thread entering the active 

            scheduler after the call to NotifyContentReadyCancel(). 

            It is valid for the client to call User::

            WaitForRequest(aNotifyRequest), where aNotifyRequest is 

            the outstanding request, immediately after calling 

            NotifyContentReadyCancel().

    */

    virtual void NotifyContentReadyCancel(const TSurfaceId& aSurface) = 0;

    };

#endif //__CONTENTREADYFORCOMPOSITION_H__