1 // Copyright (c) 2009 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 for Window Server Scene

    15 //

    16 //

    17 

    18 /**

    19  @publishedPartner

    20  @prototype

    21 */

    22 

    23 #ifndef WSSCENE_H

    24 #define WSSCENE_H

    25 

    26 #include <babitflags.h>

    27 #include <w32std.h>

    28 #include <graphics/wsgraphicdrawerinterface.h>

    29 

    30 class MWsElement;

    31 

    32 /**

    33  * @brief Window Server Scene Interface Definition.

    34  * 

    35  * MWsScene is a CWsRenderStage interface extension.  An understanding

    36  * of the Render Stage Plug-in architecture, and the CWsRenderStage API

    37  * is required in order to use and understand this interface.

    38  * 

    39  * A MWsScene manages a collection of MWsElements that define

    40  * what is shown to a User on a particular target display, or off-screen

    41  * buffer.

    42  * 

    43  * A MWsScene constitute of MWsElements.  Each MWsElement represents

    44  * a rectangular region of the screen.  MWsElements have meta-data which

    45  * describe the region, such as the image orientation, extent, and

    46  * alpha-blending characteristics.  MWsElements also have surface-data,

    47  * which provides the pixel data to be shown in the given area of the

    48  * screen.  

    49  * 

    50  * The purpose of an MWsScene is to manage the relative ordinal positions

    51  * of scene elements.  Typically elements representing the camera view-

    52  * finder, or video frames, is placed at the bottom, and the user interface

    53  * element is placed above.  Semi-transparency is often used to blend

    54  * such elements into a visually appealing scene, and transparent holes

    55  * in the user interface element allow elements below to poke through.

    56  * 

    57  * The goal of this interface is to allow suitable platforms to implement

    58  * this API using composition hardware.  This is to reduce power and

    59  * CPU load, so a long movie might be played, for example.

    60  * 

    61  * A secondary goal of this interface is to enable transition effects

    62  * to be efficiently implemented.  This is because MWsScenes can be

    63  * chained together in a Render Stage pipeline.  Element meta-data

    64  * can be manipulated by transition effects render stages before actual

    65  * rendering.

    66  * 

    67  * <h1>Examples of Elements</h1>

    68  * @li Camera view-finder

    69  * @li Video frame

    70  * @li User interface

    71  * 

    72  * There can be two types of user interface element: directly rendered

    73  * and indirectly rendered.  

    74  * 

    75  * Indirect rendering is the normal case.  Here the client provides

    76  * CWindowGc commands, which Window Server passes as MWsGraphicsContext

    77  * API calls to the Render Stage.

    78  * 

    79  * Direct rendering is where Window Server does not see the graphics

    80  * commands, as is the case for Direct Screen Access clients.

    81  * 

    82  * <h1>Use Cases</h1>

    83  * 

    84  * <h2>Instantiation</h2>

    85  * 

    86  * During system-startup Window Server needs to obtain an instance of

    87  * the MWsScene interface in order to place MWsElements in the scene

    88  * for rendering.

    89  * 

    90  * MWsScene is a CWsRenderStage interface extension, accessed by

    91  * @code

    92  * CWsRenderStage::ResolveObjectInterface(KMWsScene);

    93  * @endcode

    94  * 

    95  * The initial values are:

    96  * @li No rotation is applied

    97  * @li No Elements are in the Scene

    98  * @li Scene is connected to same display as its CWsRenderStage

    99  * 

   100  * Note Elements may be added/inserted/removed subject to implementation-

   101  * defined constraints; the connected display is immutable.

   102  * 

   103  * <h2>Rendering</h2>

   104  * 

   105  * When the Scene changes, Window Server needs to communicate the changes

   106  * and then render the new Scene.  This can happen when a video player

   107  * application is launched, whereby a new User Interface control is placed

   108  * on the screen, and a new Element representing the Video Surface is added.

   109  * 

   110  * The Window Server must use the CWsRenderStage interface to provide

   111  * updates to the Scene.

   112  * @code

   113  * CWsRenderStage::Begin(regionOfScreenWithVideoPlayer);

   114  * drawing ops sent to MWsGraphicsContext for UI

   115  * drawing ops to setup a transparent hole for video surface to poke

   116  * through

   117  * .

   118  * .

   119  * 

   120  * sceneElement = CreateSceneElementL();

   121  * sceneElement->ConnectSurface(videoSurfaceAlreadySetup);

   122  * InsertSceneElement(sceneElement, NULL);

   123  * CWsRenderStage::End(asyncCallbackNotification);

   124  * @endcode

   125  * 

   126  * When Scene updates, such as in the example above, are done there is

   127  * a concept of the "Committed Scene".  All Scene updates are considered

   128  * to be "Pending" until a CWsRenderStage::End() has been called.  Then

   129  * the pending changes are applied atomically.  Either the previously

   130  * Committed Scene is re-instated or all the Pending changes are accepted

   131  * to form the newly Committed Scene.  This depends on platform-specific

   132  * limitations, and system-wide resource availability.

   133  * 

   134  * <h2>Orientation Changes to Elements</h2>

   135  * 

   136  * Suppose we have an MWsElement representing people as seen through a video

   137  * camera view finder in landscape orientation, with the handset also in

   138  * landscape orientation.  The handset is rotated into portrait mode.

   139  * 

   140  * We desire the view finder to be rotated in the opposite

   141  * sense to the rest of the User Interface.  This is to allow people

   142  * previously vertical in the view finder to remain vertical.

   143  * 

   144  * For this use case, a MWsElement::SetSourceRotation() must be called.

   145  * 

   146  * The changes are visible after the next @c CWsRenderStage::End() call.

   147  * 

   148  * <h2>Orientation Changes to Scenes</h2>

   149  * 

   150  * Suppose the entire Scene comprises a single User Interface element.

   151  * The handset is then rotated from landscape to portrait mode.

   152  * The whole scene must be rotated to compensate.  Here 

   153  * MWsScene::SetSceneRotation() must be called.

   154  * 

   155  * The changes are visible after the next @c CWsRenderStage::End() call.

   156  * 

   157  * <h2>Leveraging external APIs for Transition Effects</h2>

   158  *

   159  * Suppose we want to manipulate the Scene to achieve a transition

   160  * effect.  The Scene as presented by Window Server comprises one

   161  * UI Element, and one External Surface Element.  We have an external

   162  * APIs, such as OpenGL or OpenWF, available to deliver a transition effect

   163  * into a different External Surface.

   164  * 

   165  * This task is accomplished by using the output Surface of OpenGL as

   166  * the connected Image Source for the one Element which comprises the Scene

   167  * presented on the Screen.

   168  * The Elements inserted into the Scene by Window Server are instead given

   169  * to OpenGL as textures.  When the Screen needs to be rendered, OpenGL

   170  * is first used to render to its output Surface, and this is taken

   171  * as-is for the Scene Element that appears on the Screen.

   172  * 

   173  * A combination of Rendering APIs may be employed if they are available

   174  * to the Transition Effects Render Stage -- to combine the power of

   175  * OpenVG, OpenGL, and OpenWF, as an example.

   176  *

   177  * <h2>Managing the life-cycle of Surfaces from Window Server</h2>

   178  *

   179  * Suppose we want to maintain the life-cycle of a given Surface outside

   180  * that needed by the Scene.  For example, suppose we have a video player

   181  * application whose picture is frozen to a particular frame.  Then the

   182  * application switches to some other view, no longer showing the video

   183  * frame.  Finally, the application switches back to the original video

   184  * frame so that the video clip can be resumed.

   185  *

   186  * In such a scenario, we would want the contents of the Surface to

   187  * remain constant event though at one point the Surface is not part

   188  * of the Scene.  This is so that the user does not see anything

   189  * inconsistent appear with the video frame between switching from and

   190  * to the video frame.

   191  *

   192  * Another scenario where the Surface needs to have a life-cycle beyond

   193  * that of the Scene is when there is a large start-up cost to populating

   194  * the Surface with initial data.  For example, a computer game application

   195  * might take some seconds to construct the textures for an initial game

   196  * position.  The game would want to construct the Surface, and populate

   197  * its contents before supplying the Surface as a Background Surface for

   198  * a given window.  This is so that the user does not see the game building

   199  * up the Surface contents during game start-up.

   200  *

   201  * To facilitate the above use case, a call to RegisterSurface and a 

   202  * corresponding call to UnregisterSurface must be made.  Note, Window

   203  * Server should provide an UnregisterSurface call if the client program

   204  * dies or exits abruptly before it could call UnregisterSurface.

   205  */

   206 class MWsScene : public MWsObjectProvider

   207     {

   208 public:

   209     DECLARE_WS_TYPE_ID(KMWsScene)

   210     

   211 public:

   212     

   213     /**

   214      * Amount of rotation of pixel data in the target display or

   215      * target surface for the entire scene.

   216      */

   217     enum TSceneRotation

   218         {

   219         ESceneAntiClockwise0 = 0,   /** No rotation */

   220         ESceneAntiClockwise90 = 1,  /** 90 Degrees Anti-clockwise in target */

   221         ESceneAntiClockwise180 = 2, /** 180 Degrees Anti-clockwise in target */

   222         ESceneAntiClockwise270 = 3  /** 270 Degrees Anti-clockwise in target */

   223         };

   224        

   225     /**

   226      * @brief   Update the rotation setting for the entire scene.

   227      * @param aSceneRotation  The new rotation setting

   228      * @note    The changes are visible after the next @c CWsRenderStage::End()

   229      *          or @c ScreenSnapshot() call.

   230      * @return  One of the system-wide error codes.  KErrArgument means

   231      *          aSceneRotation is out-of-range, KErrNotSupported means the

   232      *          setting is not supported.  KErrNone is returned upon success.

   233      */

   234     virtual TInt SetSceneRotation(const TSceneRotation aSceneRotation) = 0;

   235     

   236     /**

   237      * @brief   Obtain the current rotation setting for the entire scene

   238      * @return  The currently committed scene rotation setting.

   239      */

   240     virtual TSceneRotation SceneRotation() const = 0;

   241     

   242     /**

   243      * @brief Create a Scene Element for this scene.

   244      * 

   245      * Create a new Scene Element for use in the Scene.  The Scene Element

   246      * is immediately available to the caller, but is not in the Scene.

   247      * It must be inserted into the Scene, at which time is is considered

   248      * a Pending Scene change.  Once @c CWsRenderStage::End() has been called

   249      * the Element is rendered in the target and becomes part of the Committed

   250      * Scene.

   251      * 

   252      * @return  The Scene Element

   253      * @leave   KErrNoMemory There are insufficient memory resources

   254      */

   255     virtual MWsElement* CreateSceneElementL() = 0;

   256     

   257     /**

   258      * @brief Destroy Scene Element

   259      * 

   260      * Remove the specified element from the scene, and then destroy

   261      * resources associated with it.

   262      * 

   263      * @note  The update is seen after the next @c CWsRenderStage::End()

   264      *        call.

   265      * @param aElement  The element to destroy.  If NULL, the scene is

   266      *                  unmodified.

   267      */

   268     virtual void DestroySceneElement(MWsElement* aElement) = 0;

   269     

   270     /**

   271      * @brief Insert or Re-insert the Scene Element into the Scene

   272      * 

   273      * Insert the Scene Element into the Scene above the aSubordinateElement,

   274      * or re-insert the existing Element but into a new position in the Scene.

   275      * 

   276      * @note    The same element cannot be in the scene at more than one

   277      *          z-order position.

   278      * @pre     The element must have previously been created @c 

   279      *          CreateSceneElementL()

   280      * @return  One of the system-wide error codes.  KErrArgument means

   281      *          aElement or aSubordinateElement is not a valid element for this

   282      *          Scene.  KErrNone is returned upon success.

   283      * @param aInsertElement        The element to add; cannot be NULL

   284      * @param aSubordinateElement   The element which will be below 

   285      *                              aInsertElement when the scene is committed,

   286      *                              or NULL to place at it the bottom of

   287      *                              the scene.

   288      */

   289     virtual TInt InsertSceneElement(MWsElement* aInsertElement,

   290                                     MWsElement* aSubordinateElement) = 0;

   291     

   292     /**

   293      * @brief Remove an Element from the Scene

   294      * 

   295      * Remove the specified Element from the Scene, without destroying

   296      * it.  

   297      * 

   298      * @note   The update is seen after the next @c CWsRenderStage::End()

   299      *         call. 

   300      * @param aRemoveElement  The element to be removed from the scene.

   301      *                        If NULL, no action is taken.

   302      * @pre     The supplied element, if non-NULL, must be in the Scene;

   303      *          see @c InsertSceneElement()

   304      * @post    The removed element is no longer in the Scene, but is still

   305      *          valid object; it may receive further method calls.

   306      * @return  One of the system-wide error codes.  KErrArgument means

   307      *          aRemoveElement was not in this Scene.  KErrNone is returned

   308      *          upon success.             

   309      */

   310     virtual TInt RemoveSceneElement(MWsElement* aRemoveElement) = 0;

   311     

   312     /**

   313      * @brief Compose pending Scene into an off-screen target

   314      *

   315      * Compose the pending Scene into an off-screen target.  This

   316      * method is an asynchronous call, and signals the optionally provided

   317      * TRequestStatus, either immediately from some error cases, or later

   318      * when the supplied off-screen target has been populated.

   319      * 

   320      * However, the pending scene changes for the target screen are not

   321      * committed by this function call.

   322      * 

   323      * The TRequestStatus status value is updated by this function to one of

   324      * the system-wide error codes.  KErrArgument is set if the supplied surface

   325      * or TRequestStatus is in error.  KErrNoMemory is set for memory or other

   326      * resource failures.  KErrInUse is set if the surface is in use or

   327      * otherwise inaccessible.  KErrNotSupported is set if the supplied surface

   328      * is incompatible with the screen.

   329      *

   330      * @param aOffScreenTarget  Surface to be updated with pending

   331      *                          Scene

   332      * @param aCompleted        When non-NULL, is used to signal the

   333      *                          client when completed

   334      * @post    Either the supplied surface is updated with new contents

   335      *          and the aCompleted status is set to KErrNone, or an error value

   336      *          is set in the aCompleted status.

   337      * @post    Its guaranteed that the supplied surface is not accessed

   338      *          by MWsScene after aCompleted has been signaled.

   339      */

   340     virtual void ComposePendingScene(TSurfaceId& aOffScreenTarget,

   341                                         TRequestStatus* aCompleted) = 0;

   342     

   343     /**

   344      * @brief Register the Window Server use of a Surface

   345      *

   346      * Register the Window Server use of a Surface for this Scene.

   347      * The Scene abstraction already manages its use of Surfaces without

   348      * this method call.  The purpose of this method is to allow Window

   349      * Server, on behalf of its clients, to mark the given Surface as

   350      * being used by such clients.  This allows the Surface to maintain

   351      * a lifecycle beyond that which would normally be needed by the

   352      * Scene, and allows early indication of incompatibility between

   353      * the Surface and the Scene.

   354      *

   355      * @param aSurface  Surface to be marked as in use by the caller

   356      * @post    Either the supplied surface accepted as potentially useable

   357      *          by this Scene, or the local error value is set.

   358      * @return  One of the system-wide error codes.  KErrNotSupported means the

   359      *          Surface is incompatible with this Scene.  KErrNoMemory means

   360      *          there was a memory problem.  KErrArgument means the supplied

   361      *          Surface is not valid.  KErrServerBusy means the Surface is

   362      *          currently used by another Scene.  KErrNone is returned upon

   363      *          success.

   364      */

   365     virtual TInt RegisterSurface(const TSurfaceId& aSurface) = 0;

   366     

   367     /**

   368      * @brief Unregister the Window Server use of a Surface

   369      *

   370      * Unregister the Window Server use of a Surface with this Scene.

   371      * The Scene abstraction already manages its use of Surfaces without

   372      * this method call.  The purpose of the method is to allow Window

   373      * Server, on behalf of its clients, to mark the given Surface as

   374      * no longer in use by such clients.  This ends the lifecycle of

   375      * the Surface from the point of view of such clients.

   376      *

   377      * @param aSurface  Surface to be marked as no longer in use by the

   378      *                  caller

   379      * @return  One of the system-wide error codes.  KErrBadHandle means the 

   380      *          supplied Surface is not known.  KErrNone is returned upon 

   381      *          success.

   382      */

   383     virtual TInt UnregisterSurface(const TSurfaceId& aSurface) = 0;

   384     };

   385 #endif // WSSCENE_H