diff -r 000000000000 -r 5d03bc08d59c graphicscomposition/surfaceupdate/inc/surfaceupdateclient.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graphicscomposition/surfaceupdate/inc/surfaceupdateclient.h Tue Feb 02 01:47:50 2010 +0200 @@ -0,0 +1,320 @@ +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#ifndef __SURFACEUPDATECLIENT_H__ +#define __SURFACEUPDATECLIENT_H__ + +#include +#ifdef TEST_SURFACE_UPDATE +#include "surfaceupdate.h" +#include "surfaceupdatetest.h" +#endif + +class TSurfaceId; + +const TInt KDefaultMessageSlot = 6; + +typedef TPckgBuf TTimeStamp; + +/** +The RSurfaceUpdateSession class is intended to be used by surface update control flow. +The class implements an interface between the Compositor and clients. It allows a client to +inform the Compositor when a surface has been modified and to receive notification when +its buffer becomes available and/or displayed. +*/ +class RSurfaceUpdateSession : public RSessionBase + { +public: + IMPORT_C RSurfaceUpdateSession(); + /** + Connect to the server using given number of message slots. + + @param aMessageSlots The number of message slots available to this session. + This parameter is defined in RSessionBase specification; it signifies the maximum number + of asynchronous outstanding requests to the server. + SubmitUpdate commands could contain up to three asynchronous requests to the server, + each corresponds to a different type of notification. + + @see RSessionBase + + @pre The surface update server is started up + @post Connection to the server has been established. + + @return KErrNone if successful. + @return KErrAlreadyExists if the session has already been established. + @return KErrArgument if arguments don’t lie within expected range. + @return KErrNotFound if the server is not in operation, otherwise one of the + system-wide error codes. + */ + IMPORT_C TInt Connect(TInt aMessageSlots = KDefaultMessageSlot); + + /** + Close the session to the server. + + @pre Outstanding notification requests (if any) are cancelled. + @post The session is disconnected. + */ + IMPORT_C void Close(); + + /** + Send update message to the server. All notification requests will also be submitted at + this stage. + This is referring to when notifications are requested before the update request. +

The GCE may collapse a few requests into one. + If a few requests with different buffer numbers specified for the same surface have + been submitted at specific composition cycle, only last such request will have effect. +

Clients can send a global submit update which will be broadcast by the SUS to all + backends presented in the system. For a global update, to all screens, + the pre-defined constant KAllScreens needs to be passed as the screen parameter + to SubmitUpdate. + Note that once a Client has begun issuing SubmitUpdate with either KAllScreens or a + specific screen, then only that type of screen can be used thereafter for that + Surface Update Session, i.e. the client cannot have a mix of SubmitUpdate with + KAllScreens and specific screens. + + @see RSurfaceUpdateSession::NotifyWhenAvailable + @see RSurfaceUpdateSession::NotifyWhenDisplayed + @see RSurfaceUpdateSession::NotifyWhenDisplayedXTimes + + @param aScreen Screen number. Varies from 0 to N-1, where N is a total number of screens + in the system. If pre-defined constant KAllScreens is passed, the submission will + be broadcast to all screens. + @param aSurfaceId Secure 128-bit surface unique identifier, which fully specified the + surface. Surface ID must be assigned and registered with the GCE. + @param aBuffer Current buffer for composition. Varies from 0 to N-1, where N is the + total number of buffers in the surface. + @param aRegion The region requiring update, if this is NULL or empty, the whole + surface will be used for composition. The function doesn’t take ownership of + this parameter. + + @pre The surface session must be established to the server. + @post The GCE will trigger composition to use this region at the next composition cycle. + + @return KErrNone if a message has been transferred to the server successfully. + @return KErrArgument if arguments don’t lie within expected range. + @return KErrBackendNotAvailable if backend for specified screen hasn’t been registered + with the server. + @return KErrNotSupported if global and per-screen update are mixed within the same session. + @return KErrNoMemory if the memory is not enough to fulfill the request, + otherwise one of the system-wide error codes. + Will panic if applied on disconnected session. + */ + IMPORT_C TInt SubmitUpdate(TInt aScreen, const TSurfaceId& aSurfaceId, TInt aBuffer, + const TRegion* aDirtyRegion = NULL); + + /** + The message signals the client that the buffer associated with the notifier is available + for further updates. +

For performance reasons, the GCE uses the buffer sent by the client for composition + directly rather than composing with a copy of the buffer. + This means that, potentially, a client could be rendering to a buffer which is currently + being used for composition, leading to artefacts and possible tearing. + Depending on whether the surface is single or multi-buffered, there is some difference + in behaviour: +

  • In the case of single-buffered surfaces, the GCE will not wait for the next + submit update and will complete the request after the composition.
    • +
  • In case of multi-buffered surfaces, the GCE can postpone with the issuing the notification + to the client even after the composition with the specified surface buffer has already happened, + and issues the request when the client changes the active buffer, i.e. submits another + request for update with different buffer. This will help the GCE to keep the active buffer in a + valid state should another composition required.
    • +

    This notification enables a client to, if desired, be able to perform artefact free + rendering using this notification in conjunction with a multi-buffered surface. +

    Note that since the compositor can delay to issue request complete for multi-buffered + surface until the change of the active buffer occurs, the completion of a particular + notifier may not relate to the buffer to which it is intuitively associated. +

    Only the last call of this function before SubmitUpdate command takes place will have + effect, i.e. the following call will override the previous one. + This request will only be associated with the following single call of the SubmitUpdate. +

    When a SubmitUpdate has been broadcast to all available screen, i.e. KAllScreens was + supplied as a screen number, for multi-buffered surfaces, the notification will be completed + when the surface buffer has been released by all displays it is being shown on. + For single-buffered surfaces, notification will be completed when all displays have read + the buffer once. + + @param aStatus Reference to the request status object. + + @see RSurfaceUpdateSession::SubmitUpdate + + @pre The surface session must be established to the server. + @post This request for the consumption notification event will be transferred to the GCE + at next SubmitUpdate command. + + @return KErrNone if consumption has succeeded, the request completed aStatus will + contain this code. + @return KErrOverflow if the GCE drops the frame for composition. That could happen + if the GCE can’t cope with the current composition rate or the new request arrives + while the current is still in a progress. + The buffer overflow error can only happen with double buffering: +

  • If notification is not being used
    • +
  • If notification is not being used correctly as the client is not waiting for + notification to complete before sending a further buffer.
    • + + If an application such as video is using three (or more) buffers, this error can occur. + For instance, the video may be producing frames at a fixed rate which is faster than + the GCE can cope with, and in this case frames will be “lost”, but the notification + mechanism will still operate correctly. + + @return KErrBackendNotAvailable if backend for specified screen hasn’t been registered + with the server. + @return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range. + @return KErrCancel if notification has been cancelled. It could happen, for instance, + if CancelUpdateNotification is called before the request is completed. + @return KErrServerBusy if the number of outstanding requests has exceeded specified + value (see RSurfaceUpdateSession::Connect for details). + @return KErrNotReady if the environment is in invalid state (for instance, the Surface + Update Server has not been launched or the session is disconnected). + @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend. + @return KErrNotVisible if the surface specified in SubmitUpdate is not visible. + This could happen if there is no layer associated with the surface or no active + composition scene. + Note, the absence of this error code does not guarantee that the surface + is visible. For example, if the surface is behind another surface that has alpha blending + enabled the compositor will not do a pixel level comparison to determine surface visibility. + @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend. + @return KErrNotSupported if global and per-screen update are mixed within the same session. + @return KErrNoMemory if the memory is not enough to fulfil the request, any other + system error codes. + Will panic if applied on disconnected session. + */ + IMPORT_C void NotifyWhenAvailable(TRequestStatus& aStatus); + + /** + Ask the server to notify when the surface buffer which will be specified in the next + update request has been displayed for the first time. + The notification will also include exact time of the event as it is supplied by the + User::FastCounter(). + Only the last call of this function before SubmitUpdate command takes place will + have effect, i.e. the following call will override the previous one. + + @param aStatus Reference to the request status object. + @param aTimeStamp Reference to the timestamp of the display notification event, + packed into the modified buffer descriptor. + Will only be valid if aStatus is equal to KErrNone. + + @see RSurfaceUpdateSession::SubmitUpdate + + @pre The surface session must be established to the server. + @post This request for the display notification event will be transferred to the GCE + at next SubmitUpdate command. + + @return KErrNone if the surface has been displayed successfully, when request + completed aStatus will contain this error code. + @return KErrOverflow if the updated buffer was not displayed because it was + superseded by a further update on the same surface. + @return KErrBackendNotAvailable if backend for specified screen hasn’t been + registered with the server. + @return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range. + @return KErrCancel if notification has been cancelled. It could happen, for instance, + if CancelUpdateNotification is called before the request is completed. + @return KErrServerBusy if the number of outstanding requests has exceeded specified + value (@see RSurfaceUpdateSession::Connect for details). + @return KErrNotReady if the environment is in invalid state (for instance, the + Surface Update Server has not been launched or session is disconnected). + @return KErrNotVisible if the surface specified in SubmitUpdate is not visible. + This could happen if there is no layer associated with the surface or no active + composition scene. + For global update it signifies that the surface is not visible for any screen. + Note, the absence of this error code does not guarantee that the surface is visible. + For example, if the surface is behind another surface that has alpha blending + enabled the compositor will not do a pixel level comparison to determine surface visibility. + @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend. + @return KErrNotSupported if global and per-screen update are mixed within the same session. + @return ErrNoMemory if the memory is not enough to fulfill the request, otherwise any + other system error codes. + Will panic if applied on disconnected session. + */ + IMPORT_C void NotifyWhenDisplayed(TRequestStatus& aStatus, TTimeStamp& aTimeStamp); + + /** + Ask the server to notify when the surface buffer which will + be specified in the next update request has been displayed for the X times. +

    Only the last call of this function before SubmitUpdate command takes place + will have effect, i.e. the following call will override the previous one. +

    In case of the global update the notification will always be aligned with the master + display. The SUS will send notification to client when the surface has been displayed on a + master display for the X times or if there is no master display for that surface. + If the master becomes invisible while the request is still in a progress it will be + reassigned to the next visible display with highest priority. +

    This request will only be associated with the following single call of the SubmitUpdate. + + @param aCount Number of times the surface is displayed before the request is completed. + Varies from 1 and greater. + @param aStatus Reference to the request status object. + + @pre The surface session must be established to the server. + @post This request for the display notification event will be transferred to the GCE at + next SubmitUpdate command. + + @return KErrNone if the surface has been displayed successfully for specified numbers + of times, when request completed aStatus will contain this error code. + @return KErrOverflow if the updated buffer did not remain on-screen for the specified + number of display refreshes because it was superseded by a further update on the + same surface. + @return KErrArgument if arguments in SubmitUpdate command don’t lie within expected range. + @return KErrBackendNotAvailable if backend for specified screen hasn’t been registered + with the server. + @return KErrCancel if notification has been cancelled. It could happen, for instance, + if CancelUpdateNotification is called before the request is completed. + @return KErrServerBusy if the number of outstanding requests has exceeded + specified value (@see RSurfaceUpdateSession::Connect for details). + @return KErrNotReady if the environment is in invalid state (for instance, the + Surface Update Server has not been launched or session is disconnected). + @return KErrNotVisible if the surface specified in SubmitUpdate is not visible. + This could happen if there is no layer associated with the surface or no active + composition scene. + For global update it signifies that the surface is not visible for any screen. + Note, the absence of this error code does not guarantee that the surface is visible. + For example, if the surface is behind another surface that has alpha blending + enabled the compositor will not do a pixel level comparison to determine surface visibility. + @return KErrSurfaceNotRegistered if the surface is not registered with the specific backend. + @return KErrNotSupported if global and per-screen update are mixed within the same session. + @return KErrNoMemory if the memory is not enough to fulfill the request, otherwise + any other system error codes. + Will panic if applied on disconnected session. + */ + IMPORT_C void NotifyWhenDisplayedXTimes(TInt aCount, TRequestStatus& aStatus); + + /** + Cancel all outstanding requests for notification. + The function doesn't cancel the submit update requests themselves. + + @pre The surface session must be established to the server. + @post The server will issue request complete immediately for all outstanding requests + related to particular session. + Will panic if applied on disconnected session. + */ + IMPORT_C void CancelAllUpdateNotifications(); + +protected: + /** + Allow to retrieve the version number. + + @return client version number + */ + TVersion Version() const; + +private: + void IssueRequestComplete(TInt aErr); + +private: + TRequestStatus *iStatusAvailable; + TRequestStatus *iStatusDisplayed; + TRequestStatus *iStatusDisplayedXTimes; + TTimeStamp* iTimeStamp; + TInt iCount; + }; + +#endif