os/graphics/graphicscomposition/surfaceupdate/inc/contentreadyforcomposition.h
author sl@SLION-WIN7.fritz.box
Fri, 15 Jun 2012 03:10:57 +0200
changeset 0 bde4ae8d615e
permissions -rw-r--r--
First public contribution.
     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__