Update contrib.
1 // Copyright (c) 2006-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.
16 #ifndef __SURFACEUPDATECLIENT_H__
17 #define __SURFACEUPDATECLIENT_H__
20 #include <graphics/suerror.h>
21 #ifdef TEST_SURFACE_UPDATE
22 #include "surfaceupdate.h"
23 #include "surfaceupdatetest.h"
28 const TInt KDefaultMessageSlot = 6;
30 typedef TPckgBuf<TUint32> TTimeStamp;
33 The RSurfaceUpdateSession class is intended to be used by surface update control flow.
34 The class implements an interface between the Compositor and clients. It allows a client to
35 inform the Compositor when a surface has been modified and to receive notification when
36 its buffer becomes available and/or displayed.
38 class RSurfaceUpdateSession : public RSessionBase
41 IMPORT_C RSurfaceUpdateSession();
43 Connect to the server using given number of message slots.
45 @param aMessageSlots The number of message slots available to this session.
46 This parameter is defined in RSessionBase specification; it signifies the maximum number
47 of asynchronous outstanding requests to the server.
48 SubmitUpdate commands could contain up to three asynchronous requests to the server,
49 each corresponds to a different type of notification.
53 @pre The surface update server is started up
54 @post Connection to the server has been established.
56 @return KErrNone if successful.
57 @return KErrAlreadyExists if the session has already been established.
58 @return KErrArgument if arguments don’t lie within expected range.
59 @return KErrNotFound if the server is not in operation, otherwise one of the
60 system-wide error codes.
62 IMPORT_C TInt Connect(TInt aMessageSlots = KDefaultMessageSlot);
65 Close the session to the server.
67 @pre Outstanding notification requests (if any) are cancelled.
68 @post The session is disconnected.
70 IMPORT_C void Close();
73 Send update message to the server. All notification requests will also be submitted at
75 This is referring to when notifications are requested before the update request.
76 <p>The GCE may collapse a few requests into one.
77 If a few requests with different buffer numbers specified for the same surface have
78 been submitted at specific composition cycle, only last such request will have effect.
79 <p>Clients can send a global submit update which will be broadcast by the SUS to all
80 backends presented in the system. For a global update, to all screens,
81 the pre-defined constant KAllScreens needs to be passed as the screen parameter
83 Note that once a Client has begun issuing SubmitUpdate with either KAllScreens or a
84 specific screen, then only that type of screen can be used thereafter for that
85 Surface Update Session, i.e. the client cannot have a mix of SubmitUpdate with
86 KAllScreens and specific screens.
88 @see RSurfaceUpdateSession::NotifyWhenAvailable
89 @see RSurfaceUpdateSession::NotifyWhenDisplayed
90 @see RSurfaceUpdateSession::NotifyWhenDisplayedXTimes
92 @param aScreen Screen number. KAllScreens is the only allowed parameter.
93 @param aSurfaceId Secure 128-bit surface unique identifier, which fully specified the
94 surface. Surface ID must be assigned and registered with the GCE.
95 @param aBuffer Current buffer for composition. Varies from 0 to N-1, where N is the
96 total number of buffers in the surface.
97 @param aRegion The region requiring update, if this is NULL or empty, the whole
98 surface will be used for composition. The function doesn’t take ownership of
101 @pre The surface session must be established to the server.
102 @post The GCE will trigger composition to use this region at the next composition cycle.
104 @return KErrNone if a message has been transferred to the server successfully.
105 @return KErrArgument if arguments don’t lie within expected range.
106 @return KErrBackendNotAvailable if backend for specified screen hasn’t been registered
108 @return KErrNotSupported if global and per-screen update are mixed within the same session.
109 @return KErrNoMemory if the memory is not enough to fulfill the request,
110 otherwise one of the system-wide error codes.
111 Will panic if applied on disconnected session.
113 IMPORT_C TInt SubmitUpdate(TInt aScreen, const TSurfaceId& aSurfaceId, TInt aBuffer,
114 const TRegion* aDirtyRegion = NULL);
117 The message signals the client that the buffer associated with the notifier is available
119 <p>For performance reasons, the GCE uses the buffer sent by the client for composition
120 directly rather than composing with a copy of the buffer.
121 This means that, potentially, a client could be rendering to a buffer which is currently
122 being used for composition, leading to artefacts and possible tearing.
123 Depending on whether the surface is single or multi-buffered, there is some difference
125 <li>In the case of single-buffered surfaces, the GCE will not wait for the next
126 submit update and will complete the request after the composition. </li>
127 <li>In case of multi-buffered surfaces, the GCE can postpone with the issuing the notification
128 to the client even after the composition with the specified surface buffer has already happened,
129 and issues the request when the client changes the active buffer, i.e. submits another
130 request for update with different buffer. This will help the GCE to keep the active buffer in a
131 valid state should another composition required.</li>
132 <p>This notification enables a client to, if desired, be able to perform artefact free
133 rendering using this notification in conjunction with a multi-buffered surface.
134 <p>Note that since the compositor can delay to issue request complete for multi-buffered
135 surface until the change of the active buffer occurs, the completion of a particular
136 notifier may not relate to the buffer to which it is intuitively associated.
137 <p>Only the last call of this function before SubmitUpdate command takes place will have
138 effect, i.e. the following call will override the previous one.
139 This request will only be associated with the following single call of the SubmitUpdate.
140 <p>When a SubmitUpdate has been broadcast to all available screen, i.e. KAllScreens was
141 supplied as a screen number, for multi-buffered surfaces, the notification will be completed
142 when the surface buffer has been released by all displays it is being shown on.
143 For single-buffered surfaces, notification will be completed when all displays have read
146 @param aStatus Reference to the request status object.
148 @see RSurfaceUpdateSession::SubmitUpdate
150 @pre The surface session must be established to the server.
151 @post This request for the consumption notification event will be transferred to the GCE
152 at next SubmitUpdate command.
154 @return KErrNone if consumption has succeeded, the request completed aStatus will
156 @return KErrOverflow if the GCE drops the frame for composition. That could happen
157 if the GCE can’t cope with the current composition rate or the new request arrives
158 while the current is still in a progress.
159 The buffer overflow error can only happen with double buffering:
160 <li>If notification is not being used</li>
161 <li>If notification is not being used correctly as the client is not waiting for
162 notification to complete before sending a further buffer.</li>
164 If an application such as video is using three (or more) buffers, this error can occur.
165 For instance, the video may be producing frames at a fixed rate which is faster than
166 the GCE can cope with, and in this case frames will be “lost”, but the notification
167 mechanism will still operate correctly.
169 @return KErrBackendNotAvailable if backend for specified screen hasn’t been registered
171 @return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range.
172 @return KErrCancel if notification has been cancelled. It could happen, for instance,
173 if CancelUpdateNotification is called before the request is completed.
174 @return KErrServerBusy if the number of outstanding requests has exceeded specified
175 value (see RSurfaceUpdateSession::Connect for details).
176 @return KErrNotReady if the environment is in invalid state (for instance, the Surface
177 Update Server has not been launched or the session is disconnected).
178 @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
179 @return KErrNotVisible if the surface specified in SubmitUpdate is not visible.
180 This could happen if there is no layer associated with the surface or no active
182 Note, the absence of this error code does not guarantee that the surface
183 is visible. For example, if the surface is behind another surface that has alpha blending
184 enabled the compositor will not do a pixel level comparison to determine surface visibility.
185 @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
186 @return KErrNotSupported if global and per-screen update are mixed within the same session.
187 @return KErrNoMemory if the memory is not enough to fulfil the request, any other
189 Will panic if applied on disconnected session.
191 IMPORT_C void NotifyWhenAvailable(TRequestStatus& aStatus);
194 Ask the server to notify when the surface buffer which will be specified in the next
195 update request has been displayed for the first time.
196 The notification will also include exact time of the event as it is supplied by the
198 Only the last call of this function before SubmitUpdate command takes place will
199 have effect, i.e. the following call will override the previous one.
201 @param aStatus Reference to the request status object.
202 @param aTimeStamp Reference to the timestamp of the display notification event,
203 packed into the modified buffer descriptor.
204 Will only be valid if aStatus is equal to KErrNone.
206 @see RSurfaceUpdateSession::SubmitUpdate
208 @pre The surface session must be established to the server.
209 @post This request for the display notification event will be transferred to the GCE
210 at next SubmitUpdate command.
212 @return KErrNone if the surface has been displayed successfully, when request
213 completed aStatus will contain this error code.
214 @return KErrOverflow if the updated buffer was not displayed because it was
215 superseded by a further update on the same surface.
216 @return KErrBackendNotAvailable if backend for specified screen hasn’t been
217 registered with the server.
218 @return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range.
219 @return KErrCancel if notification has been cancelled. It could happen, for instance,
220 if CancelUpdateNotification is called before the request is completed.
221 @return KErrServerBusy if the number of outstanding requests has exceeded specified
222 value (@see RSurfaceUpdateSession::Connect for details).
223 @return KErrNotReady if the environment is in invalid state (for instance, the
224 Surface Update Server has not been launched or session is disconnected).
225 @return KErrNotVisible if the surface specified in SubmitUpdate is not visible.
226 This could happen if there is no layer associated with the surface or no active
228 For global update it signifies that the surface is not visible for any screen.
229 Note, the absence of this error code does not guarantee that the surface is visible.
230 For example, if the surface is behind another surface that has alpha blending
231 enabled the compositor will not do a pixel level comparison to determine surface visibility.
232 @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
233 @return KErrNotSupported if global and per-screen update are mixed within the same session.
234 @return ErrNoMemory if the memory is not enough to fulfill the request, otherwise any
235 other system error codes.
236 Will panic if applied on disconnected session.
238 IMPORT_C void NotifyWhenDisplayed(TRequestStatus& aStatus, TTimeStamp& aTimeStamp);
241 Ask the server to notify when the surface buffer which will
242 be specified in the next update request has been displayed for the X times.
243 <p>Only the last call of this function before SubmitUpdate command takes place
244 will have effect, i.e. the following call will override the previous one.
245 <p>In case of the global update the notification will always be aligned with the master
246 display. The SUS will send notification to client when the surface has been displayed on a
247 master display for the X times or if there is no master display for that surface.
248 If the master becomes invisible while the request is still in a progress it will be
249 reassigned to the next visible display with highest priority.
250 <p>This request will only be associated with the following single call of the SubmitUpdate.
252 @param aCount Number of times the surface is displayed before the request is completed.
253 Varies from 1 and greater.
254 @param aStatus Reference to the request status object.
256 @pre The surface session must be established to the server.
257 @post This request for the display notification event will be transferred to the GCE at
258 next SubmitUpdate command.
260 @return KErrNone if the surface has been displayed successfully for specified numbers
261 of times, when request completed aStatus will contain this error code.
262 @return KErrOverflow if the updated buffer did not remain on-screen for the specified
263 number of display refreshes because it was superseded by a further update on the
265 @return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range.
266 @return KErrBackendNotAvailable if backend for specified screen hasn’t been registered
268 @return KErrCancel if notification has been cancelled. It could happen, for instance,
269 if CancelUpdateNotification is called before the request is completed.
270 @return KErrServerBusy if the number of outstanding requests has exceeded
271 specified value (@see RSurfaceUpdateSession::Connect for details).
272 @return KErrNotReady if the environment is in invalid state (for instance, the
273 Surface Update Server has not been launched or session is disconnected).
274 @return KErrNotVisible if the surface specified in SubmitUpdate is not visible.
275 This could happen if there is no layer associated with the surface or no active
277 For global update it signifies that the surface is not visible for any screen.
278 Note, the absence of this error code does not guarantee that the surface is visible.
279 For example, if the surface is behind another surface that has alpha blending
280 enabled the compositor will not do a pixel level comparison to determine surface visibility.
281 @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
282 @return KErrNotSupported if global and per-screen update are mixed within the same session.
283 @return KErrNoMemory if the memory is not enough to fulfill the request, otherwise
284 any other system error codes.
285 Will panic if applied on disconnected session.
287 IMPORT_C void NotifyWhenDisplayedXTimes(TInt aCount, TRequestStatus& aStatus);
290 Cancel all outstanding requests for notification.
291 The function doesn't cancel the submit update requests themselves.
293 @pre The surface session must be established to the server.
294 @post The server will issue request complete immediately for all outstanding requests
295 related to particular session.
296 Will panic if applied on disconnected session.
298 IMPORT_C void CancelAllUpdateNotifications();
302 Allow to retrieve the version number.
304 @return client version number
306 TVersion Version() const;
309 void IssueRequestComplete(TInt aErr);
312 TRequestStatus *iStatusAvailable;
313 TRequestStatus *iStatusDisplayed;
314 TRequestStatus *iStatusDisplayedXTimes;
315 TTimeStamp* iTimeStamp;