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".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    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 

    17 // surface.

    18 // 

    19 //

    20 

    21 /**

    22  @file

    23  @publishedPartner

    24  @released

    25 */

    26 

    27 #ifndef __CONTENTREADYFORCOMPOSITION_H__

    28 #define __CONTENTREADYFORCOMPOSITION_H__

    29 

    30 

    31 #include <e32std.h>

    32 #include <graphics/surface.h>

    33 

    34 

    35 /**

    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 

    39 surface.

    40 

    41 The compositor maintains a content update count for each registered 

    42 surface that determines when content ready notifications will be 

    43 completed. The content update count is internally incremented by the 

    44 compositor every time it receives a valid content update for a 

    45 registered surface. Frames may be skipped if the client submits 

    46 content updates too fast, meaning that not every update is displayed 

    47 on screen. The first valid content update sets the content update 

    48 count to one. Updates sent before the surface is registered do not 

    49 affect the content update count. Content ready notifications for 

    50 aContentUpdate = 1 will only be successfully completed after at least

    51 one content update has been received.

    52 */

    53 class MContentReadyForComposition

    54     {

    55 public:

    56     enum

    57         {

    58         KUidContentReadyForComposition = 0x2002E6D5,

    59         ETypeId = KUidContentReadyForComposition

    60         };

    61 public:

    62 

    63     /**

    64     Requests a notification when a particular content update for a 

    65     given surface has been delivered to the compositor. Further, 

    66     notification implies that this newest content will be used in 

    67     future compositions until such time that newer content is 

    68     available.

    69 

    70     @param  aSurface        Id of the surface for which the

    71                             notification is required.

    72     @param  aNotifyReady    Request status that is signaled on the 

    73                             calling thread.

    74     @param  aContentUpdate  Content update number for which 

    75                             notification is required.

    76 

    77     @note   aContentUpdate is one-based. Content update one 

    78             corresponds to the first content submitted to the 

    79             compositor for a given surface.

    80 

    81     @note   If aContentUpdate is less than or equal to the current 

    82             content that the compositor uses for aSurface during 

    83             composition, aNotifyReady is completed with KErrNone 

    84             without delay. Else aNotifyReady is completed with 

    85             KErrNone when the compositor has received content update

    86             number aContentUpdate for the surface.

    87 

    88     @note   aNotifyReady is set to KRequestPending during the call

    89             to NotifyContentReady() and remains set to this value 

    90             until the request is completed with the appropriate 

    91             return code. The client must wait for this asynchronous 

    92             completion before attempting to read the return value.

    93 

    94     @note   If the registration count for aSurface becomes zero and 

    95             the surface is no longer in use in either the committed 

    96             or uncommitted scene while a notification request is 

    97             outstanding, the notification is completed with KErrAbort,

    98             without delay soon after the surface is unregistered.

    99 

   100     @note   Due to the 64-bit precision of aContentUpdate, the 

   101             probability of wrap around is considered slim and 

   102             therefore ignored. If wrap around does occur, behaviour of

   103             the API is undefined.

   104 

   105     @pre    aSurface is registered.

   106     @pre    aContentUpdate >= 1.

   107     @pre    There is no outstanding notification request for aSurface. 

   108 

   109     @error  If aSurface is not registered, aNotifyReady is completed

   110             with KErrArgument without delay.

   111     @error  If aContentUpdate == 0, aNotifyReady is completed with 

   112             KErrArgument without delay.

   113     @error  If there is an outstanding notification request for 

   114             aSurface, aNotifyReady is completed with KErrInUse without

   115             delay.

   116 

   117     @post   aNotifyReady will be signaled on the calling thread

   118             according to the above criteria.

   119     */

   120     virtual void NotifyContentReady(const TSurfaceId& aSurface, TUint64 aContentUpdate, TRequestStatus& aNotifyReady) = 0;

   121 

   122     /**

   123     Cancels a notification request made previously with 

   124     MContentReadyForComposition::NotifyContentReady() for a specific

   125     surface.

   126 

   127     @see    MContentReadyForComposition::NotifyContentReady().

   128 

   129     @param  aSurface        Id of the surface for which the 

   130                             notification request will be cancelled.

   131 

   132     @pre    aSurface is registered. 

   133     

   134     @error  If aSurface is not registered, this function is a noop.

   135 

   136     @post   If there is an outstanding notification request for 

   137             aSurface at the time of the call, it is completed with 

   138             KErrCancel without delay on the thread that originally 

   139             called NotifyContentReady() to make the request. If there

   140             is no outstanding notification request, this function is 

   141             a noop.

   142 

   143     @note   Completion of an outstanding request with KErrCancel

   144             must not rely on the calling thread entering the active 

   145             scheduler after the call to NotifyContentReadyCancel(). 

   146             It is valid for the client to call User::

   147             WaitForRequest(aNotifyRequest), where aNotifyRequest is 

   148             the outstanding request, immediately after calling 

   149             NotifyContentReadyCancel().

   150     */

   151     virtual void NotifyContentReadyCancel(const TSurfaceId& aSurface) = 0;

   152     };

   153 

   154 

   155 #endif //__CONTENTREADYFORCOMPOSITION_H__