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

    53 */

    54 class MContentReadyForComposition

    55     {

    56 public:

    57     enum

    58         {

    59         KUidContentReadyForComposition = 0x2002E6D5,

    60         ETypeId = KUidContentReadyForComposition

    61         };

    62 public:

    63 

    64     /**

    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 

    69     available.

    70 

    71     @param  aSurface        Id of the surface for which the

    72                             notification is required.

    73     @param  aNotifyReady    Request status that is signaled on the 

    74                             calling thread.

    75     @param  aContentUpdate  Content update number for which 

    76                             notification is required.

    77 

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

    79             corresponds to the first content submitted to the 

    80             compositor for a given surface.

    81 

    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.

    88 

    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.

    94 

    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.

   100 

   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.

   105 

   106     @pre    aSurface is registered.

   107     @pre    aContentUpdate >= 1.

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

   109 

   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

   116             delay.

   117 

   118     @post   aNotifyReady will be signaled on the calling thread

   119             according to the above criteria.

   120     */

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

   122 

   123     /**

   124     Cancels a notification request made previously with 

   125     MContentReadyForComposition::NotifyContentReady() for a specific

   126     surface.

   127 

   128     @see    MContentReadyForComposition::NotifyContentReady().

   129 

   130     @param  aSurface        Id of the surface for which the 

   131                             notification request will be cancelled.

   132 

   133     @pre    aSurface is registered. 

   134     

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

   136 

   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 

   142             a noop.

   143 

   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().

   151     */

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

   153     };

   154 

   155 

   156 #endif //__CONTENTREADYFORCOMPOSITION_H__