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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Interface for Window Server Scene
26 #include <babitflags.h>
28 #include <graphics/wsgraphicdrawerinterface.h>
33 * @brief Window Server Scene Interface Definition.
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.
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
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
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.
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.
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
67 * <h1>Examples of Elements</h1>
68 * @li Camera view-finder
72 * There can be two types of user interface element: directly rendered
73 * and indirectly rendered.
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.
79 * Direct rendering is where Window Server does not see the graphics
80 * commands, as is the case for Direct Screen Access clients.
84 * <h2>Instantiation</h2>
86 * During system-startup Window Server needs to obtain an instance of
87 * the MWsScene interface in order to place MWsElements in the scene
90 * MWsScene is a CWsRenderStage interface extension, accessed by
92 * CWsRenderStage::ResolveObjectInterface(KMWsScene);
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
100 * Note Elements may be added/inserted/removed subject to implementation-
101 * defined constraints; the connected display is immutable.
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.
110 * The Window Server must use the CWsRenderStage interface to provide
111 * updates to the Scene.
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
120 * sceneElement = CreateSceneElementL();
121 * sceneElement->ConnectSurface(videoSurfaceAlreadySetup);
122 * InsertSceneElement(sceneElement, NULL);
123 * CWsRenderStage::End(asyncCallbackNotification);
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.
134 * <h2>Orientation Changes to Elements</h2>
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.
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.
144 * For this use case, a MWsElement::SetSourceRotation() must be called.
146 * The changes are visible after the next @c CWsRenderStage::End() call.
148 * <h2>Orientation Changes to Scenes</h2>
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.
155 * The changes are visible after the next @c CWsRenderStage::End() call.
157 * <h2>Leveraging external APIs for Transition Effects</h2>
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.
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.
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.
177 * <h2>Managing the life-cycle of Surfaces from Window Server</h2>
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.
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.
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.
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.
206 class MWsScene : public MWsObjectProvider
209 DECLARE_WS_TYPE_ID(KMWsScene)
214 * Amount of rotation of pixel data in the target display or
215 * target surface for the entire scene.
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 */
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.
234 virtual TInt SetSceneRotation(const TSceneRotation aSceneRotation) = 0;
237 * @brief Obtain the current rotation setting for the entire scene
238 * @return The currently committed scene rotation setting.
240 virtual TSceneRotation SceneRotation() const = 0;
243 * @brief Create a Scene Element for this scene.
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
252 * @return The Scene Element
253 * @leave KErrNoMemory There are insufficient memory resources
255 virtual MWsElement* CreateSceneElementL() = 0;
258 * @brief Destroy Scene Element
260 * Remove the specified element from the scene, and then destroy
261 * resources associated with it.
263 * @note The update is seen after the next @c CWsRenderStage::End()
265 * @param aElement The element to destroy. If NULL, the scene is
268 virtual void DestroySceneElement(MWsElement* aElement) = 0;
271 * @brief Insert or Re-insert the Scene Element into the Scene
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.
276 * @note The same element cannot be in the scene at more than one
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
289 virtual TInt InsertSceneElement(MWsElement* aInsertElement,
290 MWsElement* aSubordinateElement) = 0;
293 * @brief Remove an Element from the Scene
295 * Remove the specified Element from the Scene, without destroying
298 * @note The update is seen after the next @c CWsRenderStage::End()
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
310 virtual TInt RemoveSceneElement(MWsElement* aRemoveElement) = 0;
313 * @brief Compose pending Scene into an off-screen target
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.
320 * However, the pending scene changes for the target screen are not
321 * committed by this function call.
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.
330 * @param aOffScreenTarget Surface to be updated with pending
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.
340 virtual void ComposePendingScene(TSurfaceId& aOffScreenTarget,
341 TRequestStatus* aCompleted) = 0;
344 * @brief Register the Window Server use of a Surface
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.
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
365 virtual TInt RegisterSurface(const TSurfaceId& aSurface) = 0;
368 * @brief Unregister the Window Server use of a Surface
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.
377 * @param aSurface Surface to be marked as no longer in use by the
379 * @return One of the system-wide error codes. KErrBadHandle means the
380 * supplied Surface is not known. KErrNone is returned upon
383 virtual TInt UnregisterSurface(const TSurfaceId& aSurface) = 0;