// Copyright (c) 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:

// Interface for Window Server Scene

//

//

/**

 @publishedPartner

 @prototype

*/

#ifndef WSSCENE_H

#define WSSCENE_H

#include <babitflags.h>

#include <w32std.h>

#include <graphics/wsgraphicdrawerinterface.h>

class MWsElement;

/**

 * @brief Window Server Scene Interface Definition.

 * 

 * MWsScene is a CWsRenderStage interface extension.  An understanding

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

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

 * 

 * A MWsScene manages a collection of MWsElements that define

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

 * buffer.

 * 

 * A MWsScene constitute of MWsElements.  Each MWsElement represents

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

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

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

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

 * screen.  

 * 

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

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

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

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

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

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

 * 

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

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

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

 * 

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

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

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

 * can be manipulated by transition effects render stages before actual

 * rendering.

 * 

 * <h1>Examples of Elements</h1>

 * @li Camera view-finder

 * @li Video frame

 * @li User interface

 * 

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

 * and indirectly rendered.  

 * 

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

 * CWindowGc commands, which Window Server passes as MWsGraphicsContext

 * API calls to the Render Stage.

 * 

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

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

 * 

 * <h1>Use Cases</h1>

 * 

 * <h2>Instantiation</h2>

 * 

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

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

 * for rendering.

 * 

 * MWsScene is a CWsRenderStage interface extension, accessed by

 * @code

 * CWsRenderStage::ResolveObjectInterface(KMWsScene);

 * @endcode

 * 

 * The initial values are:

 * @li No rotation is applied

 * @li No Elements are in the Scene

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

 * 

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

 * defined constraints; the connected display is immutable.

 * 

 * <h2>Rendering</h2>

 * 

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

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

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

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

 * 

 * The Window Server must use the CWsRenderStage interface to provide

 * updates to the Scene.

 * @code

 * CWsRenderStage::Begin(regionOfScreenWithVideoPlayer);

 * drawing ops sent to MWsGraphicsContext for UI

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

 * through

 * .

 * .

 * 

 * sceneElement = CreateSceneElementL();

 * sceneElement->ConnectSurface(videoSurfaceAlreadySetup);

 * InsertSceneElement(sceneElement, NULL);

 * CWsRenderStage::End(asyncCallbackNotification);

 * @endcode

 * 

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

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

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

 * the pending changes are applied atomically.  Either the previously

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

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

 * limitations, and system-wide resource availability.

 * 

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

 * 

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

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

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

 * 

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

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

 * previously vertical in the view finder to remain vertical.

 * 

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

 * 

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

 * 

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

 * 

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

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

 * The whole scene must be rotated to compensate.  Here 

 * MWsScene::SetSceneRotation() must be called.

 * 

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

 * 

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

 *

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

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

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

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

 * into a different External Surface.

 * 

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

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

 * presented on the Screen.

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

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

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

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

 * 

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

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

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

 *

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

 *

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

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

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

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

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

 * frame so that the video clip can be resumed.

 *

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

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

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

 * inconsistent appear with the video frame between switching from and

 * to the video frame.

 *

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

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

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

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

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

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

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

 * up the Surface contents during game start-up.

 *

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

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

 * Server should provide an UnregisterSurface call if the client program

 * dies or exits abruptly before it could call UnregisterSurface.

 */

class MWsScene : public MWsObjectProvider

    {

public:

    DECLARE_WS_TYPE_ID(KMWsScene)

public:

    /**

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

     * target surface for the entire scene.

     */

    enum TSceneRotation

        {

        ESceneAntiClockwise0 = 0,   /** No rotation */

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

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

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

        };

    /**

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

     * @param aSceneRotation  The new rotation setting

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

     *          or @c ScreenSnapshot() call.

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

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

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

     */

    virtual TInt SetSceneRotation(const TSceneRotation aSceneRotation) = 0;

    /**

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

     * @return  The currently committed scene rotation setting.

     */

    virtual TSceneRotation SceneRotation() const = 0;

    /**

     * @brief Create a Scene Element for this scene.

     * 

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

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

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

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

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

     * Scene.

     * 

     * @return  The Scene Element

     * @leave   KErrNoMemory There are insufficient memory resources

     */

    virtual MWsElement* CreateSceneElementL() = 0;

    /**

     * @brief Destroy Scene Element

     * 

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

     * resources associated with it.

     * 

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

     *        call.

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

     *                  unmodified.

     */

    virtual void DestroySceneElement(MWsElement* aElement) = 0;

    /**

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

     * 

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

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

     * 

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

     *          z-order position.

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

     *          CreateSceneElementL()

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

     *          aElement or aSubordinateElement is not a valid element for this

     *          Scene.  KErrNone is returned upon success.

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

     * @param aSubordinateElement   The element which will be below 

     *                              aInsertElement when the scene is committed,

     *                              or NULL to place at it the bottom of

     *                              the scene.

     */

    virtual TInt InsertSceneElement(MWsElement* aInsertElement,

                                    MWsElement* aSubordinateElement) = 0;

    /**

     * @brief Remove an Element from the Scene

     * 

     * Remove the specified Element from the Scene, without destroying

     * it.  

     * 

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

     *         call. 

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

     *                        If NULL, no action is taken.

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

     *          see @c InsertSceneElement()

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

     *          valid object; it may receive further method calls.

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

     *          aRemoveElement was not in this Scene.  KErrNone is returned

     *          upon success.             

     */

    virtual TInt RemoveSceneElement(MWsElement* aRemoveElement) = 0;

    /**

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

     *

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

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

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

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

     * 

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

     * committed by this function call.

     * 

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

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

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

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

     * otherwise inaccessible.  KErrNotSupported is set if the supplied surface

     * is incompatible with the screen.

     *

     * @param aOffScreenTarget  Surface to be updated with pending

     *                          Scene

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

     *                          client when completed

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

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

     *          is set in the aCompleted status.

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

     *          by MWsScene after aCompleted has been signaled.

     */

    virtual void ComposePendingScene(TSurfaceId& aOffScreenTarget,

                                        TRequestStatus* aCompleted) = 0;

    /**

     * @brief Register the Window Server use of a Surface

     *

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

     * The Scene abstraction already manages its use of Surfaces without

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

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

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

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

     * Scene, and allows early indication of incompatibility between

     * the Surface and the Scene.

     *

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

     * @post    Either the supplied surface accepted as potentially useable

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

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

     *          Surface is incompatible with this Scene.  KErrNoMemory means

     *          there was a memory problem.  KErrArgument means the supplied

     *          Surface is not valid.  KErrServerBusy means the Surface is

     *          currently used by another Scene.  KErrNone is returned upon

     *          success.

     */

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

    /**

     * @brief Unregister the Window Server use of a Surface

     *

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

     * The Scene abstraction already manages its use of Surfaces without

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

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

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

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

     *

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

     *                  caller

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

     *          supplied Surface is not known.  KErrNone is returned upon 

     *          success.

     */

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

    };

#endif // WSSCENE_H