1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/windowing/windowserver/inc/Graphics/openwfc/wsscene.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,385 @@
1.4 +// Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Interface for Window Server Scene
1.18 +//
1.19 +//
1.20 +
1.21 +/**
1.22 + @publishedPartner
1.23 + @prototype
1.24 +*/
1.25 +
1.26 +#ifndef WSSCENE_H
1.27 +#define WSSCENE_H
1.28 +
1.29 +#include <babitflags.h>
1.30 +#include <w32std.h>
1.31 +#include <graphics/wsgraphicdrawerinterface.h>
1.32 +
1.33 +class MWsElement;
1.34 +
1.35 +/**
1.36 + * @brief Window Server Scene Interface Definition.
1.37 + *
1.38 + * MWsScene is a CWsRenderStage interface extension. An understanding
1.39 + * of the Render Stage Plug-in architecture, and the CWsRenderStage API
1.40 + * is required in order to use and understand this interface.
1.41 + *
1.42 + * A MWsScene manages a collection of MWsElements that define
1.43 + * what is shown to a User on a particular target display, or off-screen
1.44 + * buffer.
1.45 + *
1.46 + * A MWsScene constitute of MWsElements. Each MWsElement represents
1.47 + * a rectangular region of the screen. MWsElements have meta-data which
1.48 + * describe the region, such as the image orientation, extent, and
1.49 + * alpha-blending characteristics. MWsElements also have surface-data,
1.50 + * which provides the pixel data to be shown in the given area of the
1.51 + * screen.
1.52 + *
1.53 + * The purpose of an MWsScene is to manage the relative ordinal positions
1.54 + * of scene elements. Typically elements representing the camera view-
1.55 + * finder, or video frames, is placed at the bottom, and the user interface
1.56 + * element is placed above. Semi-transparency is often used to blend
1.57 + * such elements into a visually appealing scene, and transparent holes
1.58 + * in the user interface element allow elements below to poke through.
1.59 + *
1.60 + * The goal of this interface is to allow suitable platforms to implement
1.61 + * this API using composition hardware. This is to reduce power and
1.62 + * CPU load, so a long movie might be played, for example.
1.63 + *
1.64 + * A secondary goal of this interface is to enable transition effects
1.65 + * to be efficiently implemented. This is because MWsScenes can be
1.66 + * chained together in a Render Stage pipeline. Element meta-data
1.67 + * can be manipulated by transition effects render stages before actual
1.68 + * rendering.
1.69 + *
1.70 + * <h1>Examples of Elements</h1>
1.71 + * @li Camera view-finder
1.72 + * @li Video frame
1.73 + * @li User interface
1.74 + *
1.75 + * There can be two types of user interface element: directly rendered
1.76 + * and indirectly rendered.
1.77 + *
1.78 + * Indirect rendering is the normal case. Here the client provides
1.79 + * CWindowGc commands, which Window Server passes as MWsGraphicsContext
1.80 + * API calls to the Render Stage.
1.81 + *
1.82 + * Direct rendering is where Window Server does not see the graphics
1.83 + * commands, as is the case for Direct Screen Access clients.
1.84 + *
1.85 + * <h1>Use Cases</h1>
1.86 + *
1.87 + * <h2>Instantiation</h2>
1.88 + *
1.89 + * During system-startup Window Server needs to obtain an instance of
1.90 + * the MWsScene interface in order to place MWsElements in the scene
1.91 + * for rendering.
1.92 + *
1.93 + * MWsScene is a CWsRenderStage interface extension, accessed by
1.94 + * @code
1.95 + * CWsRenderStage::ResolveObjectInterface(KMWsScene);
1.96 + * @endcode
1.97 + *
1.98 + * The initial values are:
1.99 + * @li No rotation is applied
1.100 + * @li No Elements are in the Scene
1.101 + * @li Scene is connected to same display as its CWsRenderStage
1.102 + *
1.103 + * Note Elements may be added/inserted/removed subject to implementation-
1.104 + * defined constraints; the connected display is immutable.
1.105 + *
1.106 + * <h2>Rendering</h2>
1.107 + *
1.108 + * When the Scene changes, Window Server needs to communicate the changes
1.109 + * and then render the new Scene. This can happen when a video player
1.110 + * application is launched, whereby a new User Interface control is placed
1.111 + * on the screen, and a new Element representing the Video Surface is added.
1.112 + *
1.113 + * The Window Server must use the CWsRenderStage interface to provide
1.114 + * updates to the Scene.
1.115 + * @code
1.116 + * CWsRenderStage::Begin(regionOfScreenWithVideoPlayer);
1.117 + * drawing ops sent to MWsGraphicsContext for UI
1.118 + * drawing ops to setup a transparent hole for video surface to poke
1.119 + * through
1.120 + * .
1.121 + * .
1.122 + *
1.123 + * sceneElement = CreateSceneElementL();
1.124 + * sceneElement->ConnectSurface(videoSurfaceAlreadySetup);
1.125 + * InsertSceneElement(sceneElement, NULL);
1.126 + * CWsRenderStage::End(asyncCallbackNotification);
1.127 + * @endcode
1.128 + *
1.129 + * When Scene updates, such as in the example above, are done there is
1.130 + * a concept of the "Committed Scene". All Scene updates are considered
1.131 + * to be "Pending" until a CWsRenderStage::End() has been called. Then
1.132 + * the pending changes are applied atomically. Either the previously
1.133 + * Committed Scene is re-instated or all the Pending changes are accepted
1.134 + * to form the newly Committed Scene. This depends on platform-specific
1.135 + * limitations, and system-wide resource availability.
1.136 + *
1.137 + * <h2>Orientation Changes to Elements</h2>
1.138 + *
1.139 + * Suppose we have an MWsElement representing people as seen through a video
1.140 + * camera view finder in landscape orientation, with the handset also in
1.141 + * landscape orientation. The handset is rotated into portrait mode.
1.142 + *
1.143 + * We desire the view finder to be rotated in the opposite
1.144 + * sense to the rest of the User Interface. This is to allow people
1.145 + * previously vertical in the view finder to remain vertical.
1.146 + *
1.147 + * For this use case, a MWsElement::SetSourceRotation() must be called.
1.148 + *
1.149 + * The changes are visible after the next @c CWsRenderStage::End() call.
1.150 + *
1.151 + * <h2>Orientation Changes to Scenes</h2>
1.152 + *
1.153 + * Suppose the entire Scene comprises a single User Interface element.
1.154 + * The handset is then rotated from landscape to portrait mode.
1.155 + * The whole scene must be rotated to compensate. Here
1.156 + * MWsScene::SetSceneRotation() must be called.
1.157 + *
1.158 + * The changes are visible after the next @c CWsRenderStage::End() call.
1.159 + *
1.160 + * <h2>Leveraging external APIs for Transition Effects</h2>
1.161 + *
1.162 + * Suppose we want to manipulate the Scene to achieve a transition
1.163 + * effect. The Scene as presented by Window Server comprises one
1.164 + * UI Element, and one External Surface Element. We have an external
1.165 + * APIs, such as OpenGL or OpenWF, available to deliver a transition effect
1.166 + * into a different External Surface.
1.167 + *
1.168 + * This task is accomplished by using the output Surface of OpenGL as
1.169 + * the connected Image Source for the one Element which comprises the Scene
1.170 + * presented on the Screen.
1.171 + * The Elements inserted into the Scene by Window Server are instead given
1.172 + * to OpenGL as textures. When the Screen needs to be rendered, OpenGL
1.173 + * is first used to render to its output Surface, and this is taken
1.174 + * as-is for the Scene Element that appears on the Screen.
1.175 + *
1.176 + * A combination of Rendering APIs may be employed if they are available
1.177 + * to the Transition Effects Render Stage -- to combine the power of
1.178 + * OpenVG, OpenGL, and OpenWF, as an example.
1.179 + *
1.180 + * <h2>Managing the life-cycle of Surfaces from Window Server</h2>
1.181 + *
1.182 + * Suppose we want to maintain the life-cycle of a given Surface outside
1.183 + * that needed by the Scene. For example, suppose we have a video player
1.184 + * application whose picture is frozen to a particular frame. Then the
1.185 + * application switches to some other view, no longer showing the video
1.186 + * frame. Finally, the application switches back to the original video
1.187 + * frame so that the video clip can be resumed.
1.188 + *
1.189 + * In such a scenario, we would want the contents of the Surface to
1.190 + * remain constant event though at one point the Surface is not part
1.191 + * of the Scene. This is so that the user does not see anything
1.192 + * inconsistent appear with the video frame between switching from and
1.193 + * to the video frame.
1.194 + *
1.195 + * Another scenario where the Surface needs to have a life-cycle beyond
1.196 + * that of the Scene is when there is a large start-up cost to populating
1.197 + * the Surface with initial data. For example, a computer game application
1.198 + * might take some seconds to construct the textures for an initial game
1.199 + * position. The game would want to construct the Surface, and populate
1.200 + * its contents before supplying the Surface as a Background Surface for
1.201 + * a given window. This is so that the user does not see the game building
1.202 + * up the Surface contents during game start-up.
1.203 + *
1.204 + * To facilitate the above use case, a call to RegisterSurface and a
1.205 + * corresponding call to UnregisterSurface must be made. Note, Window
1.206 + * Server should provide an UnregisterSurface call if the client program
1.207 + * dies or exits abruptly before it could call UnregisterSurface.
1.208 + */
1.209 +class MWsScene : public MWsObjectProvider
1.210 + {
1.211 +public:
1.212 + DECLARE_WS_TYPE_ID(KMWsScene)
1.213 +
1.214 +public:
1.215 +
1.216 + /**
1.217 + * Amount of rotation of pixel data in the target display or
1.218 + * target surface for the entire scene.
1.219 + */
1.220 + enum TSceneRotation
1.221 + {
1.222 + ESceneAntiClockwise0 = 0, /** No rotation */
1.223 + ESceneAntiClockwise90 = 1, /** 90 Degrees Anti-clockwise in target */
1.224 + ESceneAntiClockwise180 = 2, /** 180 Degrees Anti-clockwise in target */
1.225 + ESceneAntiClockwise270 = 3 /** 270 Degrees Anti-clockwise in target */
1.226 + };
1.227 +
1.228 + /**
1.229 + * @brief Update the rotation setting for the entire scene.
1.230 + * @param aSceneRotation The new rotation setting
1.231 + * @note The changes are visible after the next @c CWsRenderStage::End()
1.232 + * or @c ScreenSnapshot() call.
1.233 + * @return One of the system-wide error codes. KErrArgument means
1.234 + * aSceneRotation is out-of-range, KErrNotSupported means the
1.235 + * setting is not supported. KErrNone is returned upon success.
1.236 + */
1.237 + virtual TInt SetSceneRotation(const TSceneRotation aSceneRotation) = 0;
1.238 +
1.239 + /**
1.240 + * @brief Obtain the current rotation setting for the entire scene
1.241 + * @return The currently committed scene rotation setting.
1.242 + */
1.243 + virtual TSceneRotation SceneRotation() const = 0;
1.244 +
1.245 + /**
1.246 + * @brief Create a Scene Element for this scene.
1.247 + *
1.248 + * Create a new Scene Element for use in the Scene. The Scene Element
1.249 + * is immediately available to the caller, but is not in the Scene.
1.250 + * It must be inserted into the Scene, at which time is is considered
1.251 + * a Pending Scene change. Once @c CWsRenderStage::End() has been called
1.252 + * the Element is rendered in the target and becomes part of the Committed
1.253 + * Scene.
1.254 + *
1.255 + * @return The Scene Element
1.256 + * @leave KErrNoMemory There are insufficient memory resources
1.257 + */
1.258 + virtual MWsElement* CreateSceneElementL() = 0;
1.259 +
1.260 + /**
1.261 + * @brief Destroy Scene Element
1.262 + *
1.263 + * Remove the specified element from the scene, and then destroy
1.264 + * resources associated with it.
1.265 + *
1.266 + * @note The update is seen after the next @c CWsRenderStage::End()
1.267 + * call.
1.268 + * @param aElement The element to destroy. If NULL, the scene is
1.269 + * unmodified.
1.270 + */
1.271 + virtual void DestroySceneElement(MWsElement* aElement) = 0;
1.272 +
1.273 + /**
1.274 + * @brief Insert or Re-insert the Scene Element into the Scene
1.275 + *
1.276 + * Insert the Scene Element into the Scene above the aSubordinateElement,
1.277 + * or re-insert the existing Element but into a new position in the Scene.
1.278 + *
1.279 + * @note The same element cannot be in the scene at more than one
1.280 + * z-order position.
1.281 + * @pre The element must have previously been created @c
1.282 + * CreateSceneElementL()
1.283 + * @return One of the system-wide error codes. KErrArgument means
1.284 + * aElement or aSubordinateElement is not a valid element for this
1.285 + * Scene. KErrNone is returned upon success.
1.286 + * @param aInsertElement The element to add; cannot be NULL
1.287 + * @param aSubordinateElement The element which will be below
1.288 + * aInsertElement when the scene is committed,
1.289 + * or NULL to place at it the bottom of
1.290 + * the scene.
1.291 + */
1.292 + virtual TInt InsertSceneElement(MWsElement* aInsertElement,
1.293 + MWsElement* aSubordinateElement) = 0;
1.294 +
1.295 + /**
1.296 + * @brief Remove an Element from the Scene
1.297 + *
1.298 + * Remove the specified Element from the Scene, without destroying
1.299 + * it.
1.300 + *
1.301 + * @note The update is seen after the next @c CWsRenderStage::End()
1.302 + * call.
1.303 + * @param aRemoveElement The element to be removed from the scene.
1.304 + * If NULL, no action is taken.
1.305 + * @pre The supplied element, if non-NULL, must be in the Scene;
1.306 + * see @c InsertSceneElement()
1.307 + * @post The removed element is no longer in the Scene, but is still
1.308 + * valid object; it may receive further method calls.
1.309 + * @return One of the system-wide error codes. KErrArgument means
1.310 + * aRemoveElement was not in this Scene. KErrNone is returned
1.311 + * upon success.
1.312 + */
1.313 + virtual TInt RemoveSceneElement(MWsElement* aRemoveElement) = 0;
1.314 +
1.315 + /**
1.316 + * @brief Compose pending Scene into an off-screen target
1.317 + *
1.318 + * Compose the pending Scene into an off-screen target. This
1.319 + * method is an asynchronous call, and signals the optionally provided
1.320 + * TRequestStatus, either immediately from some error cases, or later
1.321 + * when the supplied off-screen target has been populated.
1.322 + *
1.323 + * However, the pending scene changes for the target screen are not
1.324 + * committed by this function call.
1.325 + *
1.326 + * The TRequestStatus status value is updated by this function to one of
1.327 + * the system-wide error codes. KErrArgument is set if the supplied surface
1.328 + * or TRequestStatus is in error. KErrNoMemory is set for memory or other
1.329 + * resource failures. KErrInUse is set if the surface is in use or
1.330 + * otherwise inaccessible. KErrNotSupported is set if the supplied surface
1.331 + * is incompatible with the screen.
1.332 + *
1.333 + * @param aOffScreenTarget Surface to be updated with pending
1.334 + * Scene
1.335 + * @param aCompleted When non-NULL, is used to signal the
1.336 + * client when completed
1.337 + * @post Either the supplied surface is updated with new contents
1.338 + * and the aCompleted status is set to KErrNone, or an error value
1.339 + * is set in the aCompleted status.
1.340 + * @post Its guaranteed that the supplied surface is not accessed
1.341 + * by MWsScene after aCompleted has been signaled.
1.342 + */
1.343 + virtual void ComposePendingScene(TSurfaceId& aOffScreenTarget,
1.344 + TRequestStatus* aCompleted) = 0;
1.345 +
1.346 + /**
1.347 + * @brief Register the Window Server use of a Surface
1.348 + *
1.349 + * Register the Window Server use of a Surface for this Scene.
1.350 + * The Scene abstraction already manages its use of Surfaces without
1.351 + * this method call. The purpose of this method is to allow Window
1.352 + * Server, on behalf of its clients, to mark the given Surface as
1.353 + * being used by such clients. This allows the Surface to maintain
1.354 + * a lifecycle beyond that which would normally be needed by the
1.355 + * Scene, and allows early indication of incompatibility between
1.356 + * the Surface and the Scene.
1.357 + *
1.358 + * @param aSurface Surface to be marked as in use by the caller
1.359 + * @post Either the supplied surface accepted as potentially useable
1.360 + * by this Scene, or the local error value is set.
1.361 + * @return One of the system-wide error codes. KErrNotSupported means the
1.362 + * Surface is incompatible with this Scene. KErrNoMemory means
1.363 + * there was a memory problem. KErrArgument means the supplied
1.364 + * Surface is not valid. KErrServerBusy means the Surface is
1.365 + * currently used by another Scene. KErrNone is returned upon
1.366 + * success.
1.367 + */
1.368 + virtual TInt RegisterSurface(const TSurfaceId& aSurface) = 0;
1.369 +
1.370 + /**
1.371 + * @brief Unregister the Window Server use of a Surface
1.372 + *
1.373 + * Unregister the Window Server use of a Surface with this Scene.
1.374 + * The Scene abstraction already manages its use of Surfaces without
1.375 + * this method call. The purpose of the method is to allow Window
1.376 + * Server, on behalf of its clients, to mark the given Surface as
1.377 + * no longer in use by such clients. This ends the lifecycle of
1.378 + * the Surface from the point of view of such clients.
1.379 + *
1.380 + * @param aSurface Surface to be marked as no longer in use by the
1.381 + * caller
1.382 + * @return One of the system-wide error codes. KErrBadHandle means the
1.383 + * supplied Surface is not known. KErrNone is returned upon
1.384 + * success.
1.385 + */
1.386 + virtual TInt UnregisterSurface(const TSurfaceId& aSurface) = 0;
1.387 + };
1.388 +#endif // WSSCENE_H