os/graphics/graphicscomposition/surfaceupdate/inc/surfaceupdateclient.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.
sl@0
     1
// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0
     2
// All rights reserved.
sl@0
     3
// This component and the accompanying materials are made available
sl@0
     4
// under the terms of "Eclipse Public License v1.0"
sl@0
     5
// which accompanies this distribution, and is available
sl@0
     6
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0
     7
//
sl@0
     8
// Initial Contributors:
sl@0
     9
// Nokia Corporation - initial contribution.
sl@0
    10
//
sl@0
    11
// Contributors:
sl@0
    12
//
sl@0
    13
// Description:
sl@0
    14
//
sl@0
    15
sl@0
    16
#ifndef __SURFACEUPDATECLIENT_H__
sl@0
    17
#define __SURFACEUPDATECLIENT_H__
sl@0
    18
sl@0
    19
#include <e32std.h>
sl@0
    20
#include <graphics/suerror.h>
sl@0
    21
#ifdef TEST_SURFACE_UPDATE
sl@0
    22
#include "surfaceupdate.h"
sl@0
    23
#include "surfaceupdatetest.h"
sl@0
    24
#endif
sl@0
    25
sl@0
    26
class TSurfaceId;
sl@0
    27
sl@0
    28
const TInt KDefaultMessageSlot = 6;
sl@0
    29
sl@0
    30
typedef TPckgBuf<TUint32> TTimeStamp;
sl@0
    31
sl@0
    32
/**
sl@0
    33
The RSurfaceUpdateSession class is intended to be used by surface update control flow.
sl@0
    34
The class implements an interface between the Compositor and clients. It allows a client to 
sl@0
    35
inform the Compositor when a surface has been modified and to receive notification when 
sl@0
    36
its buffer becomes available and/or displayed. 
sl@0
    37
*/
sl@0
    38
class RSurfaceUpdateSession : public RSessionBase
sl@0
    39
	{
sl@0
    40
public:
sl@0
    41
	IMPORT_C RSurfaceUpdateSession();
sl@0
    42
	/**
sl@0
    43
	Connect to the server using given number of message slots.
sl@0
    44
sl@0
    45
	@param aMessageSlots The number of message slots available to this session.  
sl@0
    46
	This parameter is defined in RSessionBase specification; it signifies the maximum number 
sl@0
    47
	of asynchronous outstanding requests to the server.  
sl@0
    48
	SubmitUpdate commands could contain up to three asynchronous requests to the server, 
sl@0
    49
	each corresponds to a different type of notification. 
sl@0
    50
sl@0
    51
	@see RSessionBase
sl@0
    52
sl@0
    53
	@pre The surface update server is started up
sl@0
    54
	@post Connection to the server has been established. 
sl@0
    55
sl@0
    56
	@return KErrNone if successful. 
sl@0
    57
	@return KErrAlreadyExists if the session has already been established.
sl@0
    58
	@return KErrArgument if arguments donít lie within expected range. 
sl@0
    59
	@return KErrNotFound if the server is not in operation, otherwise one of the 
sl@0
    60
	    system-wide error codes.
sl@0
    61
	*/
sl@0
    62
	IMPORT_C TInt Connect(TInt aMessageSlots = KDefaultMessageSlot);
sl@0
    63
sl@0
    64
	/**
sl@0
    65
	Close the session to the server. 
sl@0
    66
sl@0
    67
	@pre Outstanding notification requests (if any) are cancelled.
sl@0
    68
	@post The session is disconnected.
sl@0
    69
	*/
sl@0
    70
	IMPORT_C void Close();	
sl@0
    71
sl@0
    72
	/**
sl@0
    73
	Send update message to the server. All notification requests will also be submitted at 
sl@0
    74
	this stage. 
sl@0
    75
	This is referring to when notifications are requested before the update request.
sl@0
    76
	<p>The GCE may collapse a few requests into one. 
sl@0
    77
	If a few requests with different buffer numbers specified for the same surface have 
sl@0
    78
	been submitted at specific composition cycle, only last such request will have effect. 
sl@0
    79
	<p>Clients can send a global submit update which will be broadcast by the SUS to all 
sl@0
    80
	backends presented in the system. For a global update, to all screens, 
sl@0
    81
	the pre-defined constant KAllScreens needs to be passed as the screen parameter 
sl@0
    82
	to SubmitUpdate. 
sl@0
    83
	Note that once a Client has begun issuing SubmitUpdate with either KAllScreens or a 
sl@0
    84
	specific screen, then only that type of screen can be used thereafter for that 
sl@0
    85
	Surface Update Session, i.e. the client cannot have a mix of SubmitUpdate with 
sl@0
    86
	KAllScreens and specific screens.
sl@0
    87
sl@0
    88
	@see RSurfaceUpdateSession::NotifyWhenAvailable
sl@0
    89
	@see RSurfaceUpdateSession::NotifyWhenDisplayed 
sl@0
    90
	@see RSurfaceUpdateSession::NotifyWhenDisplayedXTimes  
sl@0
    91
sl@0
    92
	@param aScreen Screen number. KAllScreens is the only allowed parameter. 
sl@0
    93
	@param aSurfaceId Secure 128-bit surface unique  identifier, which fully specified the 
sl@0
    94
	    surface. Surface ID must be assigned and registered with the GCE.
sl@0
    95
	@param aBuffer Current buffer for composition. Varies from 0 to N-1, where N is the 
sl@0
    96
	    total number of buffers in the surface.
sl@0
    97
	@param aRegion The region requiring update, if this is NULL or empty, the whole 
sl@0
    98
	    surface will be used for composition. The function doesnít take ownership of 
sl@0
    99
	    this parameter.
sl@0
   100
sl@0
   101
	@pre The surface session must be established to the server.
sl@0
   102
	@post The GCE will trigger composition to use this region at the next composition cycle. 
sl@0
   103
sl@0
   104
	@return KErrNone if a message has been transferred to the server successfully. 
sl@0
   105
	@return KErrArgument if arguments donít lie within expected range.
sl@0
   106
	@return KErrBackendNotAvailable if backend for specified screen hasnít been registered 
sl@0
   107
	    with the server.
sl@0
   108
	@return KErrNotSupported if global and per-screen update are mixed within the same session.
sl@0
   109
	@return KErrNoMemory if the memory is not enough to fulfill the request, 
sl@0
   110
	    otherwise one of the system-wide error codes.
sl@0
   111
	Will panic if applied on disconnected session.
sl@0
   112
	*/
sl@0
   113
	IMPORT_C TInt SubmitUpdate(TInt aScreen, const TSurfaceId& aSurfaceId, TInt aBuffer, 
sl@0
   114
						const TRegion* aDirtyRegion = NULL);
sl@0
   115
sl@0
   116
	/**
sl@0
   117
	The message signals the client that the buffer associated with the notifier is available 
sl@0
   118
	for further updates.
sl@0
   119
	<p>For performance reasons, the GCE uses the buffer sent by the client for composition 
sl@0
   120
	directly rather than composing with a copy of the buffer. 
sl@0
   121
	This means that, potentially, a client could be rendering to a buffer which is currently 
sl@0
   122
	being used for composition, leading to artefacts and possible tearing.
sl@0
   123
	Depending on whether the surface is single or multi-buffered, there is some difference 
sl@0
   124
	in behaviour:  
sl@0
   125
	<li>In the case of single-buffered surfaces, the GCE will not wait for the next 
sl@0
   126
	submit update and will complete the request after the composition. </li>
sl@0
   127
	<li>In case of multi-buffered surfaces, the GCE can postpone with the issuing the notification 
sl@0
   128
	to the client even after the composition with the specified surface buffer has already happened, 
sl@0
   129
	and issues the request when the client changes the active buffer, i.e. submits another 
sl@0
   130
	request for update with different buffer. This will help the GCE to keep the active buffer in a 
sl@0
   131
	valid state should another composition required.</li> 
sl@0
   132
	<p>This notification enables a client to, if desired, be able to perform artefact free 
sl@0
   133
	rendering using this notification in conjunction with a multi-buffered surface.
sl@0
   134
	<p>Note that since the compositor can delay to issue request complete for multi-buffered 
sl@0
   135
	surface until the change of the active buffer occurs, the completion of a particular 
sl@0
   136
	notifier may not relate to the buffer to which it is intuitively associated. 
sl@0
   137
	<p>Only the last call of this function before SubmitUpdate command takes place will have 
sl@0
   138
	effect, i.e. the following call will override the previous one.
sl@0
   139
	This request will only be associated with the following single call of the SubmitUpdate.
sl@0
   140
	<p>When a SubmitUpdate has been broadcast to all available screen, i.e. KAllScreens was 
sl@0
   141
	supplied as a screen number, for multi-buffered surfaces, the notification will be completed 
sl@0
   142
	when the surface buffer has been released by all displays it is being shown on. 
sl@0
   143
	For single-buffered surfaces, notification will be completed when all displays have read 
sl@0
   144
	the buffer once.
sl@0
   145
sl@0
   146
	@param aStatus Reference to the request status object.
sl@0
   147
sl@0
   148
	@see RSurfaceUpdateSession::SubmitUpdate
sl@0
   149
sl@0
   150
	@pre The surface session must be established to the server.
sl@0
   151
	@post This request for the consumption notification event will be transferred to the GCE 
sl@0
   152
        at next SubmitUpdate command.  
sl@0
   153
sl@0
   154
	@return KErrNone if consumption has succeeded, the request completed aStatus will 
sl@0
   155
	    contain this code.  
sl@0
   156
	@return KErrOverflow if the GCE drops the frame for composition. That could happen 
sl@0
   157
	    if the GCE canít cope with the current composition rate or the new request arrives 
sl@0
   158
	    while the current is still in a progress.
sl@0
   159
	    The buffer overflow error can only happen with double buffering:
sl@0
   160
	    <li>If notification is not being used</li>
sl@0
   161
	    <li>If notification is not being used correctly as the client is not waiting for 
sl@0
   162
	    notification to complete before sending a further buffer.</li>
sl@0
   163
sl@0
   164
	    If an application such as video is using three (or more) buffers, this error can occur. 
sl@0
   165
	    For instance, the video may be producing frames at a fixed rate which is faster than 
sl@0
   166
	    the GCE can cope with, and in this case frames will be ďlostĒ, but the notification 
sl@0
   167
	    mechanism will still operate correctly.
sl@0
   168
	    
sl@0
   169
	@return KErrBackendNotAvailable if backend for specified screen hasnít been registered 
sl@0
   170
	    with the server.
sl@0
   171
	@return KErrArgument if arguments in SubmitUpdate command donít lie within expected range.
sl@0
   172
	@return KErrCancel if notification has been cancelled. It could happen, for instance, 
sl@0
   173
	    if CancelUpdateNotification is called before the request is completed.
sl@0
   174
	@return KErrServerBusy if the number of outstanding requests has exceeded specified 
sl@0
   175
	    value (see   RSurfaceUpdateSession::Connect for details).
sl@0
   176
	@return KErrNotReady if the environment is in invalid state (for instance, the Surface 
sl@0
   177
	    Update Server has not been launched or the session is disconnected).
sl@0
   178
	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
sl@0
   179
	@return KErrNotVisible if the surface specified in SubmitUpdate is not visible. 
sl@0
   180
	    This could happen if there is no layer associated with the surface or no active 
sl@0
   181
	    composition scene. 
sl@0
   182
	    Note, the absence of this error code does not guarantee that the surface 
sl@0
   183
	    is visible. For example, if the surface is behind another surface that has alpha blending
sl@0
   184
	    enabled the compositor will not do a pixel level comparison to determine surface visibility.
sl@0
   185
	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.     
sl@0
   186
	@return KErrNotSupported if global and per-screen update are mixed within the same session.
sl@0
   187
	@return KErrNoMemory if the memory is not enough to fulfil the request, any other 
sl@0
   188
	    system error codes.
sl@0
   189
	Will panic if applied on disconnected session.
sl@0
   190
	*/
sl@0
   191
	IMPORT_C void NotifyWhenAvailable(TRequestStatus& aStatus); 
sl@0
   192
sl@0
   193
	/**
sl@0
   194
	Ask the server to notify when the surface buffer which will be specified in the next 
sl@0
   195
	update request has been displayed for the first time. 
sl@0
   196
	The notification will also include exact time of the event as it is supplied by the 
sl@0
   197
	User::FastCounter(). 
sl@0
   198
	Only the last call of this function before SubmitUpdate command takes place will 
sl@0
   199
	have effect, i.e. the following call will override the previous one. 
sl@0
   200
sl@0
   201
	@param aStatus Reference to the request status object.
sl@0
   202
	@param aTimeStamp Reference to the timestamp of the display notification event, 
sl@0
   203
	   packed into the modified buffer descriptor. 
sl@0
   204
	   Will only be valid if aStatus is equal to KErrNone. 
sl@0
   205
sl@0
   206
	@see RSurfaceUpdateSession::SubmitUpdate
sl@0
   207
sl@0
   208
	@pre The surface session must be established to the server.
sl@0
   209
	@post This request for the display notification event will be transferred to the GCE 
sl@0
   210
	   at next SubmitUpdate command.
sl@0
   211
sl@0
   212
	@return KErrNone if the surface has been displayed successfully, when request 
sl@0
   213
	    completed aStatus will contain this error code.
sl@0
   214
	@return KErrOverflow if the updated buffer was not displayed because it was 
sl@0
   215
	    superseded by a further update on the same surface. 
sl@0
   216
	@return KErrBackendNotAvailable if backend for specified screen hasnít been 
sl@0
   217
	    registered with the server.
sl@0
   218
	@return KErrArgument if arguments in SubmitUpdate command donít lie within expected range.
sl@0
   219
	@return KErrCancel if notification has been cancelled. It could happen, for instance, 
sl@0
   220
	    if CancelUpdateNotification is called before the request is completed.
sl@0
   221
	@return KErrServerBusy if the number of outstanding requests has exceeded specified 
sl@0
   222
	    value (@see RSurfaceUpdateSession::Connect for details).
sl@0
   223
	@return KErrNotReady if the environment is in invalid state (for instance, the 
sl@0
   224
	    Surface Update Server has not been launched or session is disconnected).
sl@0
   225
	@return KErrNotVisible if the surface specified in SubmitUpdate is not visible. 
sl@0
   226
	    This could happen if there is no layer associated with the surface or no active 
sl@0
   227
	    composition scene.
sl@0
   228
	    For global update it signifies that the surface is not visible for any screen. 
sl@0
   229
	    Note, the absence of this error code does not guarantee that the surface is visible. 
sl@0
   230
	    For example, if the surface is behind another surface that has alpha blending
sl@0
   231
	    enabled the compositor will not do a pixel level comparison to determine surface visibility.
sl@0
   232
	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
sl@0
   233
	@return KErrNotSupported if global and per-screen update are mixed within the same session.
sl@0
   234
	@return ErrNoMemory if the memory is not enough to fulfill the request, otherwise any 
sl@0
   235
	    other system error codes. 
sl@0
   236
	Will panic if applied on disconnected session.
sl@0
   237
	*/
sl@0
   238
	IMPORT_C void NotifyWhenDisplayed(TRequestStatus& aStatus, TTimeStamp& aTimeStamp);
sl@0
   239
sl@0
   240
	/**
sl@0
   241
	Ask the server to notify when the surface buffer which will 
sl@0
   242
	be specified in the next update request has been displayed for the X times. 
sl@0
   243
	<p>Only the last call of this function before SubmitUpdate command takes place 
sl@0
   244
	will have effect, i.e. the following call will override the previous one.
sl@0
   245
	<p>In case of the global update the notification will always be aligned with the master 
sl@0
   246
	display. The SUS will send notification to client when the surface has been displayed on a 
sl@0
   247
	master display for the X times or if there is no master display for that surface. 
sl@0
   248
	If the master becomes invisible while the request is still in a progress it will be 
sl@0
   249
	reassigned to the next visible display with highest priority.
sl@0
   250
	<p>This request will only be associated with the following single call of the SubmitUpdate.
sl@0
   251
sl@0
   252
	@param aCount Number of times the surface is displayed  before the request is completed. 
sl@0
   253
	    Varies from 1 and greater. 
sl@0
   254
	@param aStatus Reference to the request status object.
sl@0
   255
sl@0
   256
	@pre The surface session must be established to the server.
sl@0
   257
	@post This request for the display notification event will be transferred to the GCE at 
sl@0
   258
	    next SubmitUpdate command.  
sl@0
   259
sl@0
   260
	@return KErrNone if the surface has been displayed successfully for specified numbers 
sl@0
   261
	    of times, when request completed aStatus will contain this error code.
sl@0
   262
	@return KErrOverflow if the updated buffer did not remain on-screen for the specified 
sl@0
   263
	    number of display refreshes because it was superseded by a further update on the 
sl@0
   264
	    same surface.
sl@0
   265
	@return KErrArgument if arguments in SubmitUpdate command donít lie within expected range.
sl@0
   266
	@return KErrBackendNotAvailable if backend for specified screen hasnít been registered 
sl@0
   267
	    with the server.
sl@0
   268
	@return KErrCancel if notification has been cancelled. It could happen, for instance, 
sl@0
   269
	    if CancelUpdateNotification is called before the request is completed.
sl@0
   270
	@return KErrServerBusy if the number of outstanding requests has exceeded 
sl@0
   271
	    specified value (@see RSurfaceUpdateSession::Connect for details).
sl@0
   272
	@return KErrNotReady if the environment is in invalid state (for instance, the 
sl@0
   273
	    Surface Update Server has not been launched or session is disconnected).
sl@0
   274
	@return KErrNotVisible if the surface specified in SubmitUpdate is not visible. 
sl@0
   275
	    This could happen if there is no layer associated with the surface or no active 
sl@0
   276
	    composition scene. 
sl@0
   277
	    For global update it signifies that the surface is not visible for any screen. 
sl@0
   278
	    Note, the absence of this error code does not guarantee that the surface is visible. 
sl@0
   279
	    For example, if the surface is behind another surface that has alpha blending
sl@0
   280
	    enabled the compositor will not do a pixel level comparison to determine surface visibility.
sl@0
   281
	@return KErrSurfaceNotRegistered if the surface is not registered with the specific backend.
sl@0
   282
	@return KErrNotSupported if global and per-screen update are mixed within the same session.
sl@0
   283
	@return KErrNoMemory if the memory is not enough to fulfill the request, otherwise 
sl@0
   284
	    any other system error codes. 
sl@0
   285
	Will panic if applied on disconnected session.
sl@0
   286
	*/
sl@0
   287
	IMPORT_C void NotifyWhenDisplayedXTimes(TInt aCount, TRequestStatus&  aStatus);
sl@0
   288
	
sl@0
   289
	/**
sl@0
   290
	Cancel all outstanding requests for notification. 
sl@0
   291
	The function doesn't cancel the submit update requests themselves.
sl@0
   292
sl@0
   293
	@pre The surface session must be established to the server.
sl@0
   294
	@post The server will issue request complete immediately for all outstanding requests 
sl@0
   295
	    related to particular session.
sl@0
   296
	Will panic if applied on disconnected session.
sl@0
   297
	*/
sl@0
   298
	IMPORT_C void CancelAllUpdateNotifications();
sl@0
   299
sl@0
   300
protected:
sl@0
   301
    /**
sl@0
   302
    Allow to retrieve the version number.
sl@0
   303
	
sl@0
   304
	@return client version number
sl@0
   305
    */
sl@0
   306
	TVersion Version() const;
sl@0
   307
sl@0
   308
private:	
sl@0
   309
	void IssueRequestComplete(TInt aErr);
sl@0
   310
sl@0
   311
private:
sl@0
   312
	TRequestStatus *iStatusAvailable;
sl@0
   313
	TRequestStatus *iStatusDisplayed;
sl@0
   314
	TRequestStatus *iStatusDisplayedXTimes;
sl@0
   315
	TTimeStamp* iTimeStamp;
sl@0
   316
	TInt iCount;
sl@0
   317
	};
sl@0
   318
sl@0
   319
#endif