1 // Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // CompositionSurfaceUpdate.h
15 // Interface to be implemented and registered with SUS by listener for surface content update messages.
17 #ifndef __COMPOSITIONSURFACEUPDATE_H__
18 #define __COMPOSITIONSURFACEUPDATE_H__
21 * \brief Interface to implement and register with SUS to receive ContentUpdated() notifications.
25 NONSHARABLE_CLASS(MCompositionSurfaceUpdate)
30 KUidCompositionSurfaceUpdate = 0x10286498,
31 ETypeId= KUidCompositionSurfaceUpdate
33 /*-------------------------------------------------------------------*//*!
34 * \brief Gets the API version number of the
37 * @return 1 for Oghma conformant implementation,
38 * 2 for Sphinx (Maybe).
39 * 3 for Native Stream first version.
40 *//*-------------------------------------------------------------------*/
42 virtual TInt ApiVersion (void) = 0;
44 /*-------------------------------------------------------------------*//*!
45 * \brief Gets the internal version number of the
48 * @return The version number of the
50 *//*-------------------------------------------------------------------*/
52 virtual TVersion InternalVersion (void) = 0;
54 /*-------------------------------------------------------------------*//*!
55 * \brief A function that responds to surface content notifications.
57 * When the contents of a surface change, this function gets called
58 * by a mechanism that is an implementation detail of the graphics
59 * driver together with the Native Stream and Compositor implementations.
60 * The call can originate from different processes and the
61 * Native Stream together with the Compositor implementation
62 * relays the information content of it, through implementation
63 * specific means, to trigger the actual composition soon after this
64 * call - this composition call should be synchronized with the
65 * refresh rate of the screen.
67 * @param aSurface The surface that has been updated.
68 * @param aBuffer The buffer of the surface to be used in
69 * composition. Integer starting from 0.
70 * @param aRegion The sub-area that has the updates. If NULL, the
71 * whole surface is considered changed.
72 * @param aStatusConsumed A request status object or NULL. If not NULL, then the
73 * request status is completed once the receiver
74 * does not anymore need the contents of the
75 * surface to render the update. This may happen
76 * before actually displaying the finished frame.
77 * @param aStatusDisplayed This is signaled after the composited frame
78 * is posted the to display for the first time after
79 * the update. After this the value in
80 * aTimeStamp is valid, if the value in the
81 * status object is KErrNone. Can be NULL, if
82 * no signal is desired.
83 * @param aTimeStamp Value of the User::FastCounter() right after the
84 * display refresh that signaled aStatusDisplayed.
85 * @param aStatusDispXTimes This is signaled when the surface has been on
86 * the screen for aDisplayedXTimes refreshes,
87 * including the update that signaled aStatusDisplayed.
88 * Can be NULL, if no signal is wanted.
89 * @param aDisplayedXTimes The number of refreshes after which aStatusDispXTimes
90 * is signaled or NULL. If values is provided, it must be
93 * @pre The MCompositionSurfaceUpdate implementation is waiting for content
94 * update notifications.
95 * @pre aSurface.IsNull() returns EFalse.
96 * @pre The surface aSurface is registered with the receiver or all status
97 * requests are completed with KErrArgument.
98 * @pre Either both aStatusDisplayed and aTimeStamp are NULL or neither
100 * @pre Either both aStatusDispXTimes and aDisplayedXTimes are NULL or
101 * neither of them are.
102 * @post The MCompositionSurfaceUpdate implementation is waiting for vsync
103 * or another synchronisation method to trigger composition,
104 * depending on cached visibility information.
105 * @note The updated region is used only as an optimisation hint.
106 * the current contents of the surface are always used for
107 * composition independent of the aRegion.
108 * @see Surface Update API Specification for further details
109 * about the semantics of the parameters and return values
110 * of the TRequestStatus objects.
111 *//*-------------------------------------------------------------------*/
113 virtual void ContentUpdated (const TSurfaceId& aSurface,
115 const TRegion* aRegion,
116 TRequestStatus* aStatusConsumed,
117 TRequestStatus* aStatusDisplayed,
119 TRequestStatus* aStatusDispXTimes,
120 TInt* aDisplayedXTimes) = 0;
122 /** Get Extension Interface.
123 * Implemented using the CBase::Extension_() mechanism
124 * Note that the pointer returned is only good for the lifetime of the called CBase derived object.
125 * @param aExtensionId The GUID/ Well-known ID of the interface
126 * @return pointer to the interface or NULL if not available
128 inline TAny* GetInterface(TUint aExtensionId);
129 /** Get Extension Interface - templated helper.
130 * Resolves the ID and returned pointer based on the class name.
131 * Note that the pointer returned is only good for the lifetime of the called CBase derived object.
132 * Class name should support ETypeId intergral value, else use non-template version.
133 * @param MClass The class of the interface with embedded GUID / Well known ID
134 * @return pointer to the interface or NULL if not available
136 template <class MClass> MClass* GetInterface()
138 return static_cast<MClass*>(GetInterface(MClass::ETypeId));
141 protected: //From CBase
142 virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1)=0;
146 inline TAny* MCompositionSurfaceUpdate::GetInterface(TUint aExtensionId)
149 //Note that extension is intentionally not overloaded in MCompositionSurfaceUpdate
150 if (this->Extension_(aExtensionId,retVal,NULL)<KErrNone)
160 #endif //__COMPOSITIONSURFACEUPDATE_H__