--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/graphicscomposition/surfaceupdate/inc/contentreadyforcomposition.h Mon May 03 13:44:32 2010 +0300
@@ -0,0 +1,155 @@
+// Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+// Interface to find out when a particular content update
+// for a given surface has been delivered to the compositor
+// and will be used in future compositions involving that
+// surface.
+//
+//
+
+/**
+ @file
+ @publishedPartner
+ @released
+*/
+
+#ifndef __CONTENTREADYFORCOMPOSITION_H__
+#define __CONTENTREADYFORCOMPOSITION_H__
+
+
+#include <e32std.h>
+#include <graphics/surface.h>
+
+
+/**
+MContentReadyForComposition is an interface to find out when a
+particular content update for a given surface has been delivered to
+the compositor and will be used in future compositions involving that
+surface.
+
+The compositor maintains a content update count for each registered
+surface that determines when content ready notifications will be
+completed. The content update count is internally incremented by the
+compositor every time it receives a valid content update for a
+registered surface. Frames may be skipped if the client submits
+content updates too fast, meaning that not every update is displayed
+on screen. The first valid content update sets the content update
+count to one. Updates sent before the surface is registered do not
+affect the content update count. Content ready notifications for
+aContentUpdate = 1 will only be successfully completed after at least
+one content update has been received.
+*/
+class MContentReadyForComposition
+ {
+public:
+ enum
+ {
+ KUidContentReadyForComposition = 0x2002E6D5,
+ ETypeId = KUidContentReadyForComposition
+ };
+public:
+
+ /**
+ Requests a notification when a particular content update for a
+ given surface has been delivered to the compositor. Further,
+ notification implies that this newest content will be used in
+ future compositions until such time that newer content is
+ available.
+
+ @param aSurface Id of the surface for which the
+ notification is required.
+ @param aNotifyReady Request status that is signaled on the
+ calling thread.
+ @param aContentUpdate Content update number for which
+ notification is required.
+
+ @note aContentUpdate is one-based. Content update one
+ corresponds to the first content submitted to the
+ compositor for a given surface.
+
+ @note If aContentUpdate is less than or equal to the current
+ content that the compositor uses for aSurface during
+ composition, aNotifyReady is completed with KErrNone
+ without delay. Else aNotifyReady is completed with
+ KErrNone when the compositor has received content update
+ number aContentUpdate for the surface.
+
+ @note aNotifyReady is set to KRequestPending during the call
+ to NotifyContentReady() and remains set to this value
+ until the request is completed with the appropriate
+ return code. The client must wait for this asynchronous
+ completion before attempting to read the return value.
+
+ @note If the registration count for aSurface becomes zero and
+ the surface is no longer in use in either the committed
+ or uncommitted scene while a notification request is
+ outstanding, the notification is completed with KErrAbort,
+ without delay soon after the surface is unregistered.
+
+ @note Due to the 64-bit precision of aContentUpdate, the
+ probability of wrap around is considered slim and
+ therefore ignored. If wrap around does occur, behaviour of
+ the API is undefined.
+
+ @pre aSurface is registered.
+ @pre aContentUpdate >= 1.
+ @pre There is no outstanding notification request for aSurface.
+
+ @error If aSurface is not registered, aNotifyReady is completed
+ with KErrArgument without delay.
+ @error If aContentUpdate == 0, aNotifyReady is completed with
+ KErrArgument without delay.
+ @error If there is an outstanding notification request for
+ aSurface, aNotifyReady is completed with KErrInUse without
+ delay.
+
+ @post aNotifyReady will be signaled on the calling thread
+ according to the above criteria.
+ */
+ virtual void NotifyContentReady(const TSurfaceId& aSurface, TUint64 aContentUpdate, TRequestStatus& aNotifyReady) = 0;
+
+ /**
+ Cancels a notification request made previously with
+ MContentReadyForComposition::NotifyContentReady() for a specific
+ surface.
+
+ @see MContentReadyForComposition::NotifyContentReady().
+
+ @param aSurface Id of the surface for which the
+ notification request will be cancelled.
+
+ @pre aSurface is registered.
+
+ @error If aSurface is not registered, this function is a noop.
+
+ @post If there is an outstanding notification request for
+ aSurface at the time of the call, it is completed with
+ KErrCancel without delay on the thread that originally
+ called NotifyContentReady() to make the request. If there
+ is no outstanding notification request, this function is
+ a noop.
+
+ @note Completion of an outstanding request with KErrCancel
+ must not rely on the calling thread entering the active
+ scheduler after the call to NotifyContentReadyCancel().
+ It is valid for the client to call User::
+ WaitForRequest(aNotifyRequest), where aNotifyRequest is
+ the outstanding request, immediately after calling
+ NotifyContentReadyCancel().
+ */
+ virtual void NotifyContentReadyCancel(const TSurfaceId& aSurface) = 0;
+ };
+
+
+#endif //__CONTENTREADYFORCOMPOSITION_H__