1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicscomposition/surfaceupdate/inc/contentreadyforcomposition.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,156 @@
1.4 +// Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Interface to find out when a particular content update
1.18 +// for a given surface has been delivered to the compositor
1.19 +// and will be used in future compositions involving that
1.20 +// surface.
1.21 +//
1.22 +//
1.23 +
1.24 +/**
1.25 + @file
1.26 + @publishedPartner
1.27 + @released
1.28 +*/
1.29 +
1.30 +#ifndef __CONTENTREADYFORCOMPOSITION_H__
1.31 +#define __CONTENTREADYFORCOMPOSITION_H__
1.32 +
1.33 +
1.34 +#include <e32std.h>
1.35 +#include <graphics/surface.h>
1.36 +
1.37 +
1.38 +/**
1.39 +MContentReadyForComposition is an interface to find out when a
1.40 +particular content update for a given surface has been delivered to
1.41 +the compositor and will be used in future compositions involving that
1.42 +surface.
1.43 +
1.44 +Each compositor in the system maintains its own content update count
1.45 +for each registered surface that determines when content ready
1.46 +notifications will be completed. Therefore the content update count is
1.47 +considered per-surface-per-screen. The content update count is
1.48 +internally incremented by the compositor every time it receives a
1.49 +valid content update for a registered surface. Frames may be skipped
1.50 +if the client submits content updates too fast, meaning that not every
1.51 +update is displayed on screen. The first valid content update sets the
1.52 +content update count to one. Updates sent before the surface is
1.53 +registered do not affect the content update count. Content ready
1.54 +notifications for aContentUpdate = 1 will only be successfully
1.55 +completed after at least one content update has been received.
1.56 +*/
1.57 +class MContentReadyForComposition
1.58 + {
1.59 +public:
1.60 + enum
1.61 + {
1.62 + KUidContentReadyForComposition = 0x2002E6D5,
1.63 + ETypeId = KUidContentReadyForComposition
1.64 + };
1.65 +public:
1.66 +
1.67 + /**
1.68 + Requests a notification when a particular content update for a
1.69 + given surface has been delivered to the compositor. Further,
1.70 + notification implies that this newest content will be used in
1.71 + future compositions until such time that newer content is
1.72 + available.
1.73 +
1.74 + @param aSurface Id of the surface for which the
1.75 + notification is required.
1.76 + @param aNotifyReady Request status that is signaled on the
1.77 + calling thread.
1.78 + @param aContentUpdate Content update number for which
1.79 + notification is required.
1.80 +
1.81 + @note aContentUpdate is one-based. Content update one
1.82 + corresponds to the first content submitted to the
1.83 + compositor for a given surface.
1.84 +
1.85 + @note If aContentUpdate is less than or equal to the current
1.86 + content that the compositor uses for aSurface during
1.87 + composition, aNotifyReady is completed with KErrNone
1.88 + without delay. Else aNotifyReady is completed with
1.89 + KErrNone when the compositor has received content update
1.90 + number aContentUpdate for the surface.
1.91 +
1.92 + @note aNotifyReady is set to KRequestPending during the call
1.93 + to NotifyContentReady() and remains set to this value
1.94 + until the request is completed with the appropriate
1.95 + return code. The client must wait for this asynchronous
1.96 + completion before attempting to read the return value.
1.97 +
1.98 + @note If the registration count for aSurface becomes zero and
1.99 + the surface is no longer in use in either the committed
1.100 + or uncommitted scene while a notification request is
1.101 + outstanding, the notification is completed with KErrAbort,
1.102 + without delay soon after the surface is unregistered.
1.103 +
1.104 + @note Due to the 64-bit precision of aContentUpdate, the
1.105 + probability of wrap around is considered slim and
1.106 + therefore ignored. If wrap around does occur, behaviour of
1.107 + the API is undefined.
1.108 +
1.109 + @pre aSurface is registered.
1.110 + @pre aContentUpdate >= 1.
1.111 + @pre There is no outstanding notification request for aSurface.
1.112 +
1.113 + @error If aSurface is not registered, aNotifyReady is completed
1.114 + with KErrArgument without delay.
1.115 + @error If aContentUpdate == 0, aNotifyReady is completed with
1.116 + KErrArgument without delay.
1.117 + @error If there is an outstanding notification request for
1.118 + aSurface, aNotifyReady is completed with KErrInUse without
1.119 + delay.
1.120 +
1.121 + @post aNotifyReady will be signaled on the calling thread
1.122 + according to the above criteria.
1.123 + */
1.124 + virtual void NotifyContentReady(const TSurfaceId& aSurface, TUint64 aContentUpdate, TRequestStatus& aNotifyReady) = 0;
1.125 +
1.126 + /**
1.127 + Cancels a notification request made previously with
1.128 + MContentReadyForComposition::NotifyContentReady() for a specific
1.129 + surface.
1.130 +
1.131 + @see MContentReadyForComposition::NotifyContentReady().
1.132 +
1.133 + @param aSurface Id of the surface for which the
1.134 + notification request will be cancelled.
1.135 +
1.136 + @pre aSurface is registered.
1.137 +
1.138 + @error If aSurface is not registered, this function is a noop.
1.139 +
1.140 + @post If there is an outstanding notification request for
1.141 + aSurface at the time of the call, it is completed with
1.142 + KErrCancel without delay on the thread that originally
1.143 + called NotifyContentReady() to make the request. If there
1.144 + is no outstanding notification request, this function is
1.145 + a noop.
1.146 +
1.147 + @note Completion of an outstanding request with KErrCancel
1.148 + must not rely on the calling thread entering the active
1.149 + scheduler after the call to NotifyContentReadyCancel().
1.150 + It is valid for the client to call User::
1.151 + WaitForRequest(aNotifyRequest), where aNotifyRequest is
1.152 + the outstanding request, immediately after calling
1.153 + NotifyContentReadyCancel().
1.154 + */
1.155 + virtual void NotifyContentReadyCancel(const TSurfaceId& aSurface) = 0;
1.156 + };
1.157 +
1.158 +
1.159 +#endif //__CONTENTREADYFORCOMPOSITION_H__