--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/windowing/windowserver/inc/Graphics/openwfc/wsscene.h Tue Feb 02 01:47:50 2010 +0200
@@ -0,0 +1,385 @@
+// 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