1 // Copyright (c) 2010 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 // Interface to find out when a particular content update
15 // for a given surface has been delivered to the compositor
16 // and will be used in future compositions involving that
27 #ifndef __CONTENTREADYFORCOMPOSITION_H__
28 #define __CONTENTREADYFORCOMPOSITION_H__
32 #include <graphics/surface.h>
36 MContentReadyForComposition is an interface to find out when a
37 particular content update for a given surface has been delivered to
38 the compositor and will be used in future compositions involving that
41 Each compositor in the system maintains its own content update count
42 for each registered surface that determines when content ready
43 notifications will be completed. Therefore the content update count is
44 considered per-surface-per-screen. The content update count is
45 internally incremented by the compositor every time it receives a
46 valid content update for a registered surface. Frames may be skipped
47 if the client submits content updates too fast, meaning that not every
48 update is displayed on screen. The first valid content update sets the
49 content update count to one. Updates sent before the surface is
50 registered do not affect the content update count. Content ready
51 notifications for aContentUpdate = 1 will only be successfully
52 completed after at least one content update has been received.
54 class MContentReadyForComposition
59 KUidContentReadyForComposition = 0x2002E6D5,
60 ETypeId = KUidContentReadyForComposition
65 Requests a notification when a particular content update for a
66 given surface has been delivered to the compositor. Further,
67 notification implies that this newest content will be used in
68 future compositions until such time that newer content is
71 @param aSurface Id of the surface for which the
72 notification is required.
73 @param aNotifyReady Request status that is signaled on the
75 @param aContentUpdate Content update number for which
76 notification is required.
78 @note aContentUpdate is one-based. Content update one
79 corresponds to the first content submitted to the
80 compositor for a given surface.
82 @note If aContentUpdate is less than or equal to the current
83 content that the compositor uses for aSurface during
84 composition, aNotifyReady is completed with KErrNone
85 without delay. Else aNotifyReady is completed with
86 KErrNone when the compositor has received content update
87 number aContentUpdate for the surface.
89 @note aNotifyReady is set to KRequestPending during the call
90 to NotifyContentReady() and remains set to this value
91 until the request is completed with the appropriate
92 return code. The client must wait for this asynchronous
93 completion before attempting to read the return value.
95 @note If the registration count for aSurface becomes zero and
96 the surface is no longer in use in either the committed
97 or uncommitted scene while a notification request is
98 outstanding, the notification is completed with KErrAbort,
99 without delay soon after the surface is unregistered.
101 @note Due to the 64-bit precision of aContentUpdate, the
102 probability of wrap around is considered slim and
103 therefore ignored. If wrap around does occur, behaviour of
104 the API is undefined.
106 @pre aSurface is registered.
107 @pre aContentUpdate >= 1.
108 @pre There is no outstanding notification request for aSurface.
110 @error If aSurface is not registered, aNotifyReady is completed
111 with KErrArgument without delay.
112 @error If aContentUpdate == 0, aNotifyReady is completed with
113 KErrArgument without delay.
114 @error If there is an outstanding notification request for
115 aSurface, aNotifyReady is completed with KErrInUse without
118 @post aNotifyReady will be signaled on the calling thread
119 according to the above criteria.
121 virtual void NotifyContentReady(const TSurfaceId& aSurface, TUint64 aContentUpdate, TRequestStatus& aNotifyReady) = 0;
124 Cancels a notification request made previously with
125 MContentReadyForComposition::NotifyContentReady() for a specific
128 @see MContentReadyForComposition::NotifyContentReady().
130 @param aSurface Id of the surface for which the
131 notification request will be cancelled.
133 @pre aSurface is registered.
135 @error If aSurface is not registered, this function is a noop.
137 @post If there is an outstanding notification request for
138 aSurface at the time of the call, it is completed with
139 KErrCancel without delay on the thread that originally
140 called NotifyContentReady() to make the request. If there
141 is no outstanding notification request, this function is
144 @note Completion of an outstanding request with KErrCancel
145 must not rely on the calling thread entering the active
146 scheduler after the call to NotifyContentReadyCancel().
147 It is valid for the client to call User::
148 WaitForRequest(aNotifyRequest), where aNotifyRequest is
149 the outstanding request, immediately after calling
150 NotifyContentReadyCancel().
152 virtual void NotifyContentReadyCancel(const TSurfaceId& aSurface) = 0;
156 #endif //__CONTENTREADYFORCOMPOSITION_H__