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