|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Interface for Window Server Scene |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @publishedPartner |
|
20 @prototype |
|
21 */ |
|
22 |
|
23 #ifndef WSSCENE_H |
|
24 #define WSSCENE_H |
|
25 |
|
26 #include <babitflags.h> |
|
27 #include <w32std.h> |
|
28 #include <graphics/wsgraphicdrawerinterface.h> |
|
29 |
|
30 class MWsElement; |
|
31 |
|
32 /** |
|
33 * @brief Window Server Scene Interface Definition. |
|
34 * |
|
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. |
|
38 * |
|
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 |
|
41 * buffer. |
|
42 * |
|
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 |
|
48 * screen. |
|
49 * |
|
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. |
|
56 * |
|
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. |
|
60 * |
|
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 |
|
65 * rendering. |
|
66 * |
|
67 * <h1>Examples of Elements</h1> |
|
68 * @li Camera view-finder |
|
69 * @li Video frame |
|
70 * @li User interface |
|
71 * |
|
72 * There can be two types of user interface element: directly rendered |
|
73 * and indirectly rendered. |
|
74 * |
|
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. |
|
78 * |
|
79 * Direct rendering is where Window Server does not see the graphics |
|
80 * commands, as is the case for Direct Screen Access clients. |
|
81 * |
|
82 * <h1>Use Cases</h1> |
|
83 * |
|
84 * <h2>Instantiation</h2> |
|
85 * |
|
86 * During system-startup Window Server needs to obtain an instance of |
|
87 * the MWsScene interface in order to place MWsElements in the scene |
|
88 * for rendering. |
|
89 * |
|
90 * MWsScene is a CWsRenderStage interface extension, accessed by |
|
91 * @code |
|
92 * CWsRenderStage::ResolveObjectInterface(KMWsScene); |
|
93 * @endcode |
|
94 * |
|
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 |
|
99 * |
|
100 * Note Elements may be added/inserted/removed subject to implementation- |
|
101 * defined constraints; the connected display is immutable. |
|
102 * |
|
103 * <h2>Rendering</h2> |
|
104 * |
|
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. |
|
109 * |
|
110 * The Window Server must use the CWsRenderStage interface to provide |
|
111 * updates to the Scene. |
|
112 * @code |
|
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 |
|
116 * through |
|
117 * . |
|
118 * . |
|
119 * |
|
120 * sceneElement = CreateSceneElementL(); |
|
121 * sceneElement->ConnectSurface(videoSurfaceAlreadySetup); |
|
122 * InsertSceneElement(sceneElement, NULL); |
|
123 * CWsRenderStage::End(asyncCallbackNotification); |
|
124 * @endcode |
|
125 * |
|
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. |
|
133 * |
|
134 * <h2>Orientation Changes to Elements</h2> |
|
135 * |
|
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. |
|
139 * |
|
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. |
|
143 * |
|
144 * For this use case, a MWsElement::SetSourceRotation() must be called. |
|
145 * |
|
146 * The changes are visible after the next @c CWsRenderStage::End() call. |
|
147 * |
|
148 * <h2>Orientation Changes to Scenes</h2> |
|
149 * |
|
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. |
|
154 * |
|
155 * The changes are visible after the next @c CWsRenderStage::End() call. |
|
156 * |
|
157 * <h2>Leveraging external APIs for Transition Effects</h2> |
|
158 * |
|
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. |
|
164 * |
|
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. |
|
172 * |
|
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. |
|
176 * |
|
177 * <h2>Managing the life-cycle of Surfaces from Window Server</h2> |
|
178 * |
|
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. |
|
185 * |
|
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. |
|
191 * |
|
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. |
|
200 * |
|
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. |
|
205 */ |
|
206 class MWsScene : public MWsObjectProvider |
|
207 { |
|
208 public: |
|
209 DECLARE_WS_TYPE_ID(KMWsScene) |
|
210 |
|
211 public: |
|
212 |
|
213 /** |
|
214 * Amount of rotation of pixel data in the target display or |
|
215 * target surface for the entire scene. |
|
216 */ |
|
217 enum TSceneRotation |
|
218 { |
|
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 */ |
|
223 }; |
|
224 |
|
225 /** |
|
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. |
|
233 */ |
|
234 virtual TInt SetSceneRotation(const TSceneRotation aSceneRotation) = 0; |
|
235 |
|
236 /** |
|
237 * @brief Obtain the current rotation setting for the entire scene |
|
238 * @return The currently committed scene rotation setting. |
|
239 */ |
|
240 virtual TSceneRotation SceneRotation() const = 0; |
|
241 |
|
242 /** |
|
243 * @brief Create a Scene Element for this scene. |
|
244 * |
|
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 |
|
250 * Scene. |
|
251 * |
|
252 * @return The Scene Element |
|
253 * @leave KErrNoMemory There are insufficient memory resources |
|
254 */ |
|
255 virtual MWsElement* CreateSceneElementL() = 0; |
|
256 |
|
257 /** |
|
258 * @brief Destroy Scene Element |
|
259 * |
|
260 * Remove the specified element from the scene, and then destroy |
|
261 * resources associated with it. |
|
262 * |
|
263 * @note The update is seen after the next @c CWsRenderStage::End() |
|
264 * call. |
|
265 * @param aElement The element to destroy. If NULL, the scene is |
|
266 * unmodified. |
|
267 */ |
|
268 virtual void DestroySceneElement(MWsElement* aElement) = 0; |
|
269 |
|
270 /** |
|
271 * @brief Insert or Re-insert the Scene Element into the Scene |
|
272 * |
|
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. |
|
275 * |
|
276 * @note The same element cannot be in the scene at more than one |
|
277 * z-order position. |
|
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 |
|
287 * the scene. |
|
288 */ |
|
289 virtual TInt InsertSceneElement(MWsElement* aInsertElement, |
|
290 MWsElement* aSubordinateElement) = 0; |
|
291 |
|
292 /** |
|
293 * @brief Remove an Element from the Scene |
|
294 * |
|
295 * Remove the specified Element from the Scene, without destroying |
|
296 * it. |
|
297 * |
|
298 * @note The update is seen after the next @c CWsRenderStage::End() |
|
299 * call. |
|
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 |
|
308 * upon success. |
|
309 */ |
|
310 virtual TInt RemoveSceneElement(MWsElement* aRemoveElement) = 0; |
|
311 |
|
312 /** |
|
313 * @brief Compose pending Scene into an off-screen target |
|
314 * |
|
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. |
|
319 * |
|
320 * However, the pending scene changes for the target screen are not |
|
321 * committed by this function call. |
|
322 * |
|
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. |
|
329 * |
|
330 * @param aOffScreenTarget Surface to be updated with pending |
|
331 * Scene |
|
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. |
|
339 */ |
|
340 virtual void ComposePendingScene(TSurfaceId& aOffScreenTarget, |
|
341 TRequestStatus* aCompleted) = 0; |
|
342 |
|
343 /** |
|
344 * @brief Register the Window Server use of a Surface |
|
345 * |
|
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. |
|
354 * |
|
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 |
|
363 * success. |
|
364 */ |
|
365 virtual TInt RegisterSurface(const TSurfaceId& aSurface) = 0; |
|
366 |
|
367 /** |
|
368 * @brief Unregister the Window Server use of a Surface |
|
369 * |
|
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. |
|
376 * |
|
377 * @param aSurface Surface to be marked as no longer in use by the |
|
378 * caller |
|
379 * @return One of the system-wide error codes. KErrBadHandle means the |
|
380 * supplied Surface is not known. KErrNone is returned upon |
|
381 * success. |
|
382 */ |
|
383 virtual TInt UnregisterSurface(const TSurfaceId& aSurface) = 0; |
|
384 }; |
|
385 #endif // WSSCENE_H |