// 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