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

// CompositionSurfaceUpdate.h

// Interface to be implemented and registered with SUS by listener for surface content update messages.  

//

#ifndef __COMPOSITIONSURFACEUPDATE_H__

#define __COMPOSITIONSURFACEUPDATE_H__

/**

 * \brief Interface to implement and register with SUS to receive ContentUpdated() notifications. 

 * 

 * 

 **/

NONSHARABLE_CLASS(MCompositionSurfaceUpdate)

    {

public:

    enum    

        {

        KUidCompositionSurfaceUpdate =  0x10286498,

        ETypeId=     KUidCompositionSurfaceUpdate 

        };

    /*-------------------------------------------------------------------*//*!

     * \brief   Gets the API version number of the

     *          implementation.

     *

     * @return  1 for Oghma conformant implementation,

     *          2 for Sphinx (Maybe).

     *          3 for Native Stream first version.

     *//*-------------------------------------------------------------------*/

        virtual TInt        ApiVersion          (void) = 0;

    /*-------------------------------------------------------------------*//*!

     * \brief   Gets the internal version number of the

     *          implementation.

     *

     * @return  The version number of the 

     *          instance.

     *//*-------------------------------------------------------------------*/

        virtual TVersion    InternalVersion     (void) = 0;

        /*-------------------------------------------------------------------*//*!

         * \brief   A function that responds to surface content notifications.

         *

         * When the contents of a surface change, this function gets called

         * by a mechanism that is an implementation detail of the graphics

         * driver together with the Native Stream and Compositor implementations. 

         * The call can originate from different processes and the

         * Native Stream together with the Compositor implementation

         * relays the information content of it, through implementation

         * specific means, to trigger the actual composition soon after this

         * call - this composition call should be synchronized with the

         * refresh rate of the screen.

         *

         * @param   aSurface            The surface that has been updated.

         * @param   aBuffer             The buffer of the surface to be used in

         *                              composition. Integer starting from 0.

         * @param   aRegion             The sub-area that has the updates. If NULL, the

         *                              whole surface is considered changed.

         * @param   aStatusConsumed     A request status object or NULL. If not NULL, then the

         *                              request status is completed once the receiver

         *                              does not anymore need the contents of the

         *                              surface to render the update. This may happen

         *                              before actually displaying the finished frame.

         * @param   aStatusDisplayed    This is signaled after the composited frame

         *                              is posted the to display for the first time after

         *                              the update. After this the value in

         *                              aTimeStamp is valid, if the value in the

         *                              status object is KErrNone. Can be NULL, if

         *                              no signal is desired.

         * @param   aTimeStamp          Value of the User::FastCounter() right after the

         *                              display refresh that signaled aStatusDisplayed.

         * @param   aStatusDispXTimes   This is signaled when the surface has been on

         *                              the screen for aDisplayedXTimes refreshes,

         *                              including the update that signaled aStatusDisplayed.

         *                              Can be NULL, if no signal is wanted.

         * @param   aDisplayedXTimes    The number of refreshes after which aStatusDispXTimes

         *                              is signaled or NULL. If values is provided, it must be

         *                              >= 1.

         *

         * @pre     The MCompositionSurfaceUpdate implementation is waiting for content

         *          update notifications.

         * @pre     aSurface.IsNull() returns EFalse.

         * @pre     The surface aSurface is registered with the receiver or all status

         *          requests are completed with KErrArgument.

         * @pre     Either both aStatusDisplayed and aTimeStamp are NULL or neither

         *          of them are.

         * @pre     Either both aStatusDispXTimes and aDisplayedXTimes are NULL or

         *          neither of them are.

         * @post    The MCompositionSurfaceUpdate implementation is waiting for vsync 

         *          or another synchronisation method to trigger composition,

         *          depending on cached visibility information.

         * @note    The updated region is used only as an optimisation hint.

         *          the current contents of the surface are always used for

         *          composition independent of the aRegion.

         * @see     Surface Update API Specification for further details

         *          about the semantics of the parameters and return values

         *          of the TRequestStatus objects.

         *//*-------------------------------------------------------------------*/

            virtual void        ContentUpdated      (const TSurfaceId&  aSurface,

                                                     TInt               aBuffer,

                                                     const TRegion*     aRegion,

                                                     TRequestStatus*    aStatusConsumed,

                                                     TRequestStatus*    aStatusDisplayed,

                                                     TUint32*           aTimeStamp,

                                                     TRequestStatus*    aStatusDispXTimes,

                                                     TInt*              aDisplayedXTimes) = 0;

public:

    /** Get Extension Interface.

     *  Implemented using the CBase::Extension_() mechanism 

     *  Note that the pointer returned is only good for the lifetime of the called CBase derived object.

     *  @param  aExtensionId    The GUID/ Well-known ID of the interface

     *  @return pointer to the interface or NULL if not available

     **/

        inline TAny* GetInterface(TUint aExtensionId);

    /** Get Extension Interface - templated helper.

     *  Resolves the ID and returned pointer based on the class name.

     *  Note that the pointer returned is only good for the lifetime of the called CBase derived object.

     *  Class name should support ETypeId intergral value, else use non-template version. 

     *  @param  MClass  The class of the interface with embedded GUID / Well known ID 

     *  @return pointer to the interface or NULL if not available

     **/

        template <class MClass> MClass* GetInterface()

        {

            return static_cast<MClass*>(GetInterface(MClass::ETypeId));

        }

protected:  //From CBase

    virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1)=0;

    };

inline TAny* MCompositionSurfaceUpdate::GetInterface(TUint aExtensionId)

    {

    TAny*   retVal=NULL;

    //Note that extension is intentionally not overloaded in MCompositionSurfaceUpdate

    if (this->Extension_(aExtensionId,retVal,NULL)<KErrNone)

        {

        return NULL;

        }

    else

        {

        return retVal;

        }

    }

#endif  //__COMPOSITIONSURFACEUPDATE_H__