1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicscomposition/surfaceupdate/inc/compositionsurfaceupdate.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,160 @@
1.4 +// Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// CompositionSurfaceUpdate.h
1.18 +// Interface to be implemented and registered with SUS by listener for surface content update messages.
1.19 +//
1.20 +#ifndef __COMPOSITIONSURFACEUPDATE_H__
1.21 +#define __COMPOSITIONSURFACEUPDATE_H__
1.22 +
1.23 +/**
1.24 + * \brief Interface to implement and register with SUS to receive ContentUpdated() notifications.
1.25 + *
1.26 + *
1.27 + **/
1.28 +NONSHARABLE_CLASS(MCompositionSurfaceUpdate)
1.29 + {
1.30 +public:
1.31 + enum
1.32 + {
1.33 + KUidCompositionSurfaceUpdate = 0x10286498,
1.34 + ETypeId= KUidCompositionSurfaceUpdate
1.35 + };
1.36 + /*-------------------------------------------------------------------*//*!
1.37 + * \brief Gets the API version number of the
1.38 + * implementation.
1.39 + *
1.40 + * @return 1 for Oghma conformant implementation,
1.41 + * 2 for Sphinx (Maybe).
1.42 + * 3 for Native Stream first version.
1.43 + *//*-------------------------------------------------------------------*/
1.44 +
1.45 + virtual TInt ApiVersion (void) = 0;
1.46 +
1.47 + /*-------------------------------------------------------------------*//*!
1.48 + * \brief Gets the internal version number of the
1.49 + * implementation.
1.50 + *
1.51 + * @return The version number of the
1.52 + * instance.
1.53 + *//*-------------------------------------------------------------------*/
1.54 +
1.55 + virtual TVersion InternalVersion (void) = 0;
1.56 +
1.57 + /*-------------------------------------------------------------------*//*!
1.58 + * \brief A function that responds to surface content notifications.
1.59 + *
1.60 + * When the contents of a surface change, this function gets called
1.61 + * by a mechanism that is an implementation detail of the graphics
1.62 + * driver together with the Native Stream and Compositor implementations.
1.63 + * The call can originate from different processes and the
1.64 + * Native Stream together with the Compositor implementation
1.65 + * relays the information content of it, through implementation
1.66 + * specific means, to trigger the actual composition soon after this
1.67 + * call - this composition call should be synchronized with the
1.68 + * refresh rate of the screen.
1.69 + *
1.70 + * @param aSurface The surface that has been updated.
1.71 + * @param aBuffer The buffer of the surface to be used in
1.72 + * composition. Integer starting from 0.
1.73 + * @param aRegion The sub-area that has the updates. If NULL, the
1.74 + * whole surface is considered changed.
1.75 + * @param aStatusConsumed A request status object or NULL. If not NULL, then the
1.76 + * request status is completed once the receiver
1.77 + * does not anymore need the contents of the
1.78 + * surface to render the update. This may happen
1.79 + * before actually displaying the finished frame.
1.80 + * @param aStatusDisplayed This is signaled after the composited frame
1.81 + * is posted the to display for the first time after
1.82 + * the update. After this the value in
1.83 + * aTimeStamp is valid, if the value in the
1.84 + * status object is KErrNone. Can be NULL, if
1.85 + * no signal is desired.
1.86 + * @param aTimeStamp Value of the User::FastCounter() right after the
1.87 + * display refresh that signaled aStatusDisplayed.
1.88 + * @param aStatusDispXTimes This is signaled when the surface has been on
1.89 + * the screen for aDisplayedXTimes refreshes,
1.90 + * including the update that signaled aStatusDisplayed.
1.91 + * Can be NULL, if no signal is wanted.
1.92 + * @param aDisplayedXTimes The number of refreshes after which aStatusDispXTimes
1.93 + * is signaled or NULL. If values is provided, it must be
1.94 + * >= 1.
1.95 + *
1.96 + * @pre The MCompositionSurfaceUpdate implementation is waiting for content
1.97 + * update notifications.
1.98 + * @pre aSurface.IsNull() returns EFalse.
1.99 + * @pre The surface aSurface is registered with the receiver or all status
1.100 + * requests are completed with KErrArgument.
1.101 + * @pre Either both aStatusDisplayed and aTimeStamp are NULL or neither
1.102 + * of them are.
1.103 + * @pre Either both aStatusDispXTimes and aDisplayedXTimes are NULL or
1.104 + * neither of them are.
1.105 + * @post The MCompositionSurfaceUpdate implementation is waiting for vsync
1.106 + * or another synchronisation method to trigger composition,
1.107 + * depending on cached visibility information.
1.108 + * @note The updated region is used only as an optimisation hint.
1.109 + * the current contents of the surface are always used for
1.110 + * composition independent of the aRegion.
1.111 + * @see Surface Update API Specification for further details
1.112 + * about the semantics of the parameters and return values
1.113 + * of the TRequestStatus objects.
1.114 + *//*-------------------------------------------------------------------*/
1.115 +
1.116 + virtual void ContentUpdated (const TSurfaceId& aSurface,
1.117 + TInt aBuffer,
1.118 + const TRegion* aRegion,
1.119 + TRequestStatus* aStatusConsumed,
1.120 + TRequestStatus* aStatusDisplayed,
1.121 + TUint32* aTimeStamp,
1.122 + TRequestStatus* aStatusDispXTimes,
1.123 + TInt* aDisplayedXTimes) = 0;
1.124 +public:
1.125 + /** Get Extension Interface.
1.126 + * Implemented using the CBase::Extension_() mechanism
1.127 + * Note that the pointer returned is only good for the lifetime of the called CBase derived object.
1.128 + * @param aExtensionId The GUID/ Well-known ID of the interface
1.129 + * @return pointer to the interface or NULL if not available
1.130 + **/
1.131 + inline TAny* GetInterface(TUint aExtensionId);
1.132 + /** Get Extension Interface - templated helper.
1.133 + * Resolves the ID and returned pointer based on the class name.
1.134 + * Note that the pointer returned is only good for the lifetime of the called CBase derived object.
1.135 + * Class name should support ETypeId intergral value, else use non-template version.
1.136 + * @param MClass The class of the interface with embedded GUID / Well known ID
1.137 + * @return pointer to the interface or NULL if not available
1.138 + **/
1.139 + template <class MClass> MClass* GetInterface()
1.140 + {
1.141 + return static_cast<MClass*>(GetInterface(MClass::ETypeId));
1.142 + }
1.143 +
1.144 +protected: //From CBase
1.145 + virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1)=0;
1.146 +
1.147 + };
1.148 +
1.149 +inline TAny* MCompositionSurfaceUpdate::GetInterface(TUint aExtensionId)
1.150 + {
1.151 + TAny* retVal=NULL;
1.152 + //Note that extension is intentionally not overloaded in MCompositionSurfaceUpdate
1.153 + if (this->Extension_(aExtensionId,retVal,NULL)<KErrNone)
1.154 + {
1.155 + return NULL;
1.156 + }
1.157 + else
1.158 + {
1.159 + return retVal;
1.160 + }
1.161 + }
1.162 +
1.163 +#endif //__COMPOSITIONSURFACEUPDATE_H__