diff -r 01a6848ebfd7 -r 36b2e23a8629 graphicscomposition/surfaceupdate/inc/contentreadyforcomposition.h --- /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 +#include + + +/** +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__