|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // CompositionSurfaceUpdate.h |
|
15 // Interface to be implemented and registered with SUS by listener for surface content update messages. |
|
16 // |
|
17 #ifndef __COMPOSITIONSURFACEUPDATE_H__ |
|
18 #define __COMPOSITIONSURFACEUPDATE_H__ |
|
19 |
|
20 /** |
|
21 * \brief Interface to implement and register with SUS to receive ContentUpdated() notifications. |
|
22 * |
|
23 * |
|
24 **/ |
|
25 NONSHARABLE_CLASS(MCompositionSurfaceUpdate) |
|
26 { |
|
27 public: |
|
28 enum |
|
29 { |
|
30 KUidCompositionSurfaceUpdate = 0x10286498, |
|
31 ETypeId= KUidCompositionSurfaceUpdate |
|
32 }; |
|
33 /*-------------------------------------------------------------------*//*! |
|
34 * \brief Gets the API version number of the |
|
35 * implementation. |
|
36 * |
|
37 * @return 1 for Oghma conformant implementation, |
|
38 * 2 for Sphinx (Maybe). |
|
39 * 3 for Native Stream first version. |
|
40 *//*-------------------------------------------------------------------*/ |
|
41 |
|
42 virtual TInt ApiVersion (void) = 0; |
|
43 |
|
44 /*-------------------------------------------------------------------*//*! |
|
45 * \brief Gets the internal version number of the |
|
46 * implementation. |
|
47 * |
|
48 * @return The version number of the |
|
49 * instance. |
|
50 *//*-------------------------------------------------------------------*/ |
|
51 |
|
52 virtual TVersion InternalVersion (void) = 0; |
|
53 |
|
54 /*-------------------------------------------------------------------*//*! |
|
55 * \brief A function that responds to surface content notifications. |
|
56 * |
|
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. |
|
66 * |
|
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 |
|
91 * >= 1. |
|
92 * |
|
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 |
|
99 * of them are. |
|
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 *//*-------------------------------------------------------------------*/ |
|
112 |
|
113 virtual void ContentUpdated (const TSurfaceId& aSurface, |
|
114 TInt aBuffer, |
|
115 const TRegion* aRegion, |
|
116 TRequestStatus* aStatusConsumed, |
|
117 TRequestStatus* aStatusDisplayed, |
|
118 TUint32* aTimeStamp, |
|
119 TRequestStatus* aStatusDispXTimes, |
|
120 TInt* aDisplayedXTimes) = 0; |
|
121 public: |
|
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 |
|
127 **/ |
|
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 |
|
135 **/ |
|
136 template <class MClass> MClass* GetInterface() |
|
137 { |
|
138 return static_cast<MClass*>(GetInterface(MClass::ETypeId)); |
|
139 } |
|
140 |
|
141 protected: //From CBase |
|
142 virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1)=0; |
|
143 |
|
144 }; |
|
145 |
|
146 inline TAny* MCompositionSurfaceUpdate::GetInterface(TUint aExtensionId) |
|
147 { |
|
148 TAny* retVal=NULL; |
|
149 //Note that extension is intentionally not overloaded in MCompositionSurfaceUpdate |
|
150 if (this->Extension_(aExtensionId,retVal,NULL)<KErrNone) |
|
151 { |
|
152 return NULL; |
|
153 } |
|
154 else |
|
155 { |
|
156 return retVal; |
|
157 } |
|
158 } |
|
159 |
|
160 #endif //__COMPOSITIONSURFACEUPDATE_H__ |