--- a/Symbian3/PDK/Source/GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita	Tue Jul 20 12:00:49 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita	Fri Aug 13 16:47:46 2010 +0100
@@ -1,281 +1,281 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License 
-"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: 
--->
-<!DOCTYPE concept
-  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336" xml:lang="en"><title>Render
-Stage Interfaces</title><shortdesc>This topic builds on the Render Stages Overview and provides an
-introduction to the main render stage interfaces. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
-audience</b>: Device creators. </p>
-<p>The <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages
-Overview</xref> introduced some of the interfaces that render stages implement.
-Here we will look at those in more detail, along with some of the other interfaces. </p>
-<section id="GUID-48000875-54A6-4563-8FC0-86320EA69D2C"><title>MWsObjectProvider</title> <p> <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> is
-a Window Server plug-in framework interface, which provides a mechanism through
-which classes can offer extension interfaces. Render stages and most of the
-related classes implement this interface. </p> </section>
-<section id="GUID-06DE55A6-6346-4F78-8F4A-320F15ADB822"><title>CWsRenderStage</title> <p> <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita"><apiname>CWsRenderStage</apiname></xref> is
-an abstract class that all render stages must derive from. It has two pure
-virtual functions: <codeph>Begin()</codeph> and <codeph>End()</codeph>, which
-must be implemented in the concrete class. </p> <p>The Window Server's output
-to the render stage pipeline is not a continuous stream, but instead consists
-of batches of drawing operations. When client drawing or server-side animations
-require a screen update, the <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">Window
-Server rendering loop</xref> schedules a redraw. When this redraw occurs,
-a batch of drawing operations is produced to perform the updates. </p> <p>The
-Window Server calls <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita#GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A/GUID-75503F6F-91DA-3392-8CD5-34FFF9095D30"><apiname>CWsRenderStage::Begin()</apiname></xref> at the beginning
-of a batch of draw operations. This gives the render stages an opportunity
-to perform any preparation. Similarly the Window Server calls <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita#GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A/GUID-0EBA06BF-D17F-3485-85B6-F4B855A48B62"><apiname>CWsRenderStage::End()</apiname></xref> at
-the end of the batch, which provides the render stages with the opportunity
-to perform any tidying up. </p> <p>For example, a flicker buffer render stage
-might use the <codeph>Begin()</codeph> call as a signal to clear its off-screen
-buffer, and the <codeph>End()</codeph> call as a signal to perform the blit
-of the accumulated updates to the next render stage. The final render stage
-might use the <codeph>End()</codeph> call as the signal to submit a surface
-update to the composition engine. </p> <p>Render stages perform all rendering
-operations between the <codeph>Begin()</codeph> and <codeph>End()</codeph> calls.
-The Window Server calls the <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> functions
-only between the <codeph>Begin()</codeph> and <codeph>End()</codeph> calls.
-The render stage could <codeph>ASSERT</codeph> that these functions are not
-called at other times and ignore them if they are or take some other action
-as appropriate. However, render stages can safely call composition context
-functions outside the <codeph>Begin()</codeph> and <codeph>End()</codeph> calls.
-In addition, the <xref href="GUID-B1E048A2-D5E8-3E7F-A6AC-6B8F3ED3067C.dita"><apiname>MWsScreenDevice</apiname></xref> functions may be called
-at any time. </p> </section>
-<section id="GUID-B189C7EB-AD1F-51C6-91F1-8EBD49D8F69D"><title>MWsGraphicsContext</title> <p> <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> is
-the interface for GDI-like drawing. The Window Server requests this interface
-from the first render stage in the chain using the object provider mechanism.
-This is a mandatory interface, which means that a render stage must not return
-null when it receives an object provider request for this interface. However,
-providing an implementation is not mandatory. For example, a logging render
-stage might simply delegate to the next render stage instead of returning
-its own implementation of this interface. </p> <p>The member functions correspond
-to functions in <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref> (such as <codeph>DrawText()</codeph> and <codeph>BitBlt()</codeph>)
-but without functions that are not suitable for hardware acceleration (such
-as read-modify-write functions like <codeph>SetFaded()</codeph>). </p> <p>The
-final render stage in the chain typically provides an implementation of <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> in
-terms of a concrete rendering context—for example, by translating into BitGDI
-or OpenVG calls. </p> <p>If <b>extended bitmaps</b> are supported on the device,
-the implementation of the functions that receive a <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> as
-an argument can check whether it is the handle to an extended bitmap. If it
-is, the render stage can process the proprietary data within the bitmap. You
-can get access to the proprietary data by using <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-2AB943ED-7DBE-3FDA-82AF-317F152EDB03"><apiname>CFbsBitmap::DataAddress()</apiname></xref>.
-Here is a simple example: </p> <codeblock id="GUID-390E236B-7EB1-5A90-B1F5-A0190403FF27" xml:space="preserve">// bmp points to a bitmap to be drawn.
-TUid type = bmp-&gt;ExtendedBitmapType();
-    
-if (type==KUidMyProprietaryFormat)
-    {    
-    bmp-&gt;BeginDataAccess();
-    const TUint32* data = bmp-&gt;DataAddress();
-    TInt dataSize = bmp-&gt;DataSize();
-    ProcessMyData(data, dataSize);
-    bmp-&gt;EndDataAccess(ETrue);
-    }
-</codeblock> <p>For some data formats, particularly those that contain vector
-data, such as SVG, this approach has advantages compared to letting the extended
-bitmap rasterizer DLL process the proprietary data. For example, the extended
-bitmap rasterizer DLL rasterizes the proprietary data into a pixel buffer,
-which is then blitted to the screen. In contrast the render stage can insert
-the drawing commands directly into the drawing command stream without the
-use of intermediate pixel buffers. In addition, unlike the extended bitmap
-rasterizer DLL, the render stage does not need to rasterize the image to a
-higher resolution in order to scale it down. The use of the render stage to
-process the proprietary data can therefore potentially save memory and improve
-performance, depending on the data format. </p> <p>Although the Symbian Foundation
-does not currently provide extended bitmap functionality in the main render
-stages, it does provide a test extended bitmap render stage. You can use this
-as an example when you implement your own extended bitmap functionality. </p> <p>For
-more information, see <xref href="GUID-D76C7759-739D-5C98-B718-7297687FE630.dita">Extended
-Bitmaps</xref>. </p> </section>
-<section id="GUID-490A69C0-E8F0-4767-965E-798C5953A8D9"><title>MWsScene </title> <p> <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> is the composition
-context interface for use with <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
-composition</xref>. It is a mandatory interface. However, like <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref>,
-some render stages might simply delegate to the next render stage rather than
-providing their own implementations. The final render stage in the chain typically
-provides an implementation of <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> in terms of OpenWF-C. </p> <p>The <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> interface
-defines the composition context for a particular screen (or an off-screen
-buffer representing the screen) in terms of a collection of rectangular regions.
-These are called <xref href="GUID-41802B91-26B3-5F3C-AE04-B6954F3804B7.dita">scene
-elements</xref> or simply <b>elements</b>. Each one is represented by the <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> interface.
-The <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> interface manages the relative ordinal positions
-of the elements and uses the elements to track external surfaces and their
-place in the composition scene. Render stages can manipulate element metadata
-in order to perform transition effects and use the hardware-accelerated composition
-facilities provided by OpenWF-C to perform transition effects (such as slide,
-zoom and fade). </p> <p>Some of the key functions are: </p> <ul>
-<li id="GUID-8265EB9F-14A5-54C5-B3EB-3925964121A5"><p> <codeph>CreateSceneElementL()</codeph>.
-Creates a new element for use in the scene. After creation, an element is
-available to the caller but <codeph>InsertSceneElement()</codeph> must be
-called to actually insert it into the pending scene. </p> </li>
-<li id="GUID-8736EC49-0C43-58AB-B9F1-397D2B7D6486"><p> <codeph>InsertSceneElement()</codeph>.
-Inserts an element into the scene. </p> </li>
-<li id="GUID-9016ACE1-E1BC-5126-A7D8-8A564CF96865"><p> <codeph>RemoveSceneElement()</codeph>.
-Removes an element from the scene. </p> </li>
-<li id="GUID-832568D5-4DCD-59CF-9982-2C6584AFC2B9"><p> <codeph>DestroySceneElement()</codeph>.
-Destroys an element and removes its resources from the scene. </p> </li>
-<li id="GUID-BA1D1346-EE28-5179-BBC9-300618162607"><p> <codeph>ComposePendingScene()</codeph>.
-Renders the pending scene to an off-screen target. </p> </li>
-<li id="GUID-AF8EFE14-B829-5B4B-998E-3CF161F027C1"><p> <codeph> RegisterSurface()</codeph>.
-Marks a surface as potentially in use beyond its lifetime within the scene.
-There are two typical use cases—one is where the contents of the surface (for
-example, a video frame) must be maintained when users switch to another application
-that hides the surface so that it is no longer part of the scene. This means
-that users can have a seamless experience when they switch back to the video.
-The other use case is where the content of a surface needs to be populated
-before it is attached to a window and therefore added to the scene. </p> </li>
-<li id="GUID-CE8BB038-0B65-5C78-B457-F7B532471826"><p> <codeph>UnregisterSurface()</codeph>.
-Marks the surface as no longer in use beyond its inclusion in the scene. </p> </li>
-</ul> <p>Any updates to the scene introduced by the render stage (such as
-adding a new element) are pending until the Window Server calls <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita#GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A/GUID-0EBA06BF-D17F-3485-85B6-F4B855A48B62"><apiname>CWsRenderStage::End()</apiname></xref> to
-commit the scene. </p> </section>
-
-<section id="GUID-2924C0EE-222B-4A23-830B-DD31A985C13F"><title>MWsElement</title> <p> <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> is a
-mandatory interface for managing scene elements when <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
-composition</xref> is in use. This interface is obtained by using <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-B776F464-8AAE-32C4-A0FF-026D8E553B7D"><apiname>MWsScene::CreateSceneElementL()</apiname></xref> rather
-than the object provider mechanism. </p> <p>The <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> interface
-provides a way of associating metadata with an image source. From the render
-stage's point of view, the image source is a surface that is connected to
-the element—whereas OpenWF-C has the concept of image sources that are created
-from native streams. Because the <xref href="GUID-83510B5B-9725-5272-BF51-23A089178DAC.dita">OpenWF-C
-Support component</xref> implements native streams in terms of Symbian surfaces,
-the render stage can ignore this distinction and simply cast the address of
-the <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref> to the OpenWF-C native stream type (<xref href="GUID-DF6DF530-EC4E-32D4-9CC8-536F3F2BE83E.dita"><apiname>WFCNativeStreamType</apiname></xref>). </p> <p>The
-element metadata includes the following: </p> <ul>
-<li id="GUID-BD2BD787-B90D-5E00-A533-7401CB4A7CB4"><p>Source rectangle—the
-region within the surface from which pixels are taken. This enables the surface
-to be cropped and is equivalent to the surface viewport described in <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External Surfaces Overview</xref>. </p> </li>
-<li id="GUID-CFD9C7F9-78EA-5719-A5F1-DD2D78ECFEE8"><p>Destination rectangle—the
-target rectangle in the composition output to which the pixels are rendered.
-This is equivalent to the extent. </p> </li>
-<li id="GUID-9EE4ECD3-7274-553B-8123-250EE3E7751A"><p>Global alpha—a global
-alpha value for use in blending the surface into the composition output. </p> </li>
-<li id="GUID-1FA2DF2A-2FBC-551B-B4D9-6D6711F46D39"><p>Source rotation—the
-number of quadrant angles by which the contents of the surface are rotated. </p> </li>
-<li id="GUID-3830D1D3-8687-5C7A-B886-F1B0CED6BF26"><p>Source flipping—a Boolean
-value that indicates whether the contents of the surface are flipped. </p> </li>
-<li id="GUID-7535C9D7-314C-5EF6-8D50-226DC5F2DE33"><p>Target renderer flags—these
-provide information to the rendering subsystem (for example, the OpenWF-C
-engine), such as whether the renderer should blend based on the global alpha
-value or the alpha channel in the surface itself. </p> </li>
-<li id="GUID-8B50BD6E-5F9A-5690-99CC-73AE8D129B52"><p>Render stage flags—these
-provide information to the render stages, such as whether the UI surface is
-always on top. </p> </li>
-</ul> </section>
-
-<section id="GUID-4A3F1B94-9EFE-47EE-A060-FAB8E92D3F3C"><title>MWsScreenDevice</title> <p> <xref href="GUID-B1E048A2-D5E8-3E7F-A6AC-6B8F3ED3067C.dita"><apiname>MWsScreenDevice</apiname></xref> is
-the interface for managing the screen. It provides functions for controlling
-rotation and fetching data from the screen such as a screen snapshot. </p> </section>
-<section id="GUID-3558E65B-F8C9-4A63-B22E-41B7E2ECB21D"><title>MWsTextCursor</title> <p> <xref href="GUID-F43CBB9C-238B-33C5-B872-AAE0104F047E.dita"><apiname>MWsTextCursor</apiname></xref> is
-an interface that enables render stages to implement a text cursor to represent
-the flashing bar or rectangle that represents the current position when editing
-text. </p> <p>Prior to the introduction of ScreenPlay text cursors were drawn
-using XOR drawing because it provides high contrast against the background.
-Render stages can implement this interface using the same approach but it
-is generally inefficient on hardware-accelerated platforms. Therefore another
-approach, such as a drop shadow or sprite, might be preferable. </p> <p>The
-preferred solution is that clients use <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-684910B9-CCEA-3798-BE23-967820BBF363"><apiname>RWsSession::SetCustomTextCursor()</apiname></xref> to
-replace the text cursor with a sprite. This means that user themes can use
-a sprite that matches the text—for example, a white sprite with white text
-and a black sprite with black text. If a client does this, the render stage’s <xref href="GUID-F43CBB9C-238B-33C5-B872-AAE0104F047E.dita"><apiname>MWsTextCursor</apiname></xref> API
-is not used when drawing text cursors for that client. Instead, the text cursor
-sprite is drawn using GDI draw operations through the <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> interface. </p> </section>
-<section id="GUID-6D6482E9-7AD7-46A1-AFFB-B98B6BAB1973"><title>MWsFader</title> <p> <xref href="GUID-1CF41CFD-27C8-39D7-A615-18CE765436DE.dita"><apiname>MWsFader</apiname></xref> is the interface
-for providing fading capabilities. </p> </section>
-<section id="GUID-EDE3C8A9-1EBB-4B8C-A483-1F469A19CCB5"><title>MWsWindowTreeObserver</title> <p> <xref href="GUID-028CC583-AC32-3D60-943A-A80F84E05DD2.dita"><apiname>MWsWindowTreeObserver</apiname></xref> is
-an optional interface that enables a render stage to create a replica of the
-window tree, known as the <b>visuals tree</b>. The Window Server uses this
-interface to tell the render stage about the window tree structure and changes
-to window tree nodes. Note that this interface considers animations and sprites
-to be nodes in the window tree. </p> <p>See the <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita#GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87/GUID-5D81D1A7-26A0-5461-9AC5-3EF359D283CB">Advanced
-Use Case</xref> section of the <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render
-Stages Overview</xref> for more information. </p> </section>
-<section id="GUID-7536F610-F9F7-5E17-82D8-623D774DC091"><title>MWsDrawAnnotationObserver</title> <p> <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita"><apiname>MWsDrawAnnotationObserver</apiname></xref> is
-an optional interface that enables render stages to associate a batch of drawing
-operations with a specific window or node in the visuals tree. TFX render
-stages generally need to implement this interface. </p> <p>If the render stage
-implements the <xref href="GUID-028CC583-AC32-3D60-943A-A80F84E05DD2.dita"><apiname>MWsWindowTreeObserver</apiname></xref> interface, implementing
-the <codeph>MWsDrawAnnotationObserver</codeph> interface enables the render
-stage to know which node in the visuals tree each batch of drawing operations
-belongs to. This means that the render stage can associate the batch with
-the correct window, sprite or other element in the visuals tree and manage
-it efficiently. </p> <p>If the render stage does <b>not</b> implement the <codeph>MWsWindowTreeObserver</codeph> interface,
-the <codeph>MWsDrawAnnotationObserver</codeph> interface still provides the
-window tree node pointers for each batch of drawing operations. There are
-two different approaches this type of render stage can take: </p> <ul>
-<li id="GUID-3248DECC-4F1E-5504-AC00-751D33D032A5"><p>The render stage can
-treat the window tree node pointers as unique identifiers for the windows.
-This approach is typically used when the Window Server's default <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">dirty-rectangle
-rendering mode</xref> is in use. In this mode the Window Server sends the
-batches of drawing operations to the first render stage in back to front z-order.
-(That is, the drawing operations for the windows in the background come before
-the drawing operations for the windows at the front.) Using the unique identifier
-and the z-order, the render stage can identify new windows that are at the
-top and slide them on or perform some other transition effect. </p> <p>This
-approach is suitable when the render stage always performs the same transition
-effect. For example, the render stage slides on all new windows that are at
-the front. </p> </li>
-<li id="GUID-F21BC536-DE1C-585C-B183-AF499AC31FC6"><p>The other approach is
-suitable when the render stage applies transition effects to specific windows;
-for example, windows that belong to a media player application. In this scenario,
-the client communicates the handles of those windows to the render stage.
-The render stage uses the <codeph>MWsDrawAnnotationObserver</codeph> to retrieve
-the handles of the windows to which the drawing operations relate. The render
-stage compares these handles with those communicated by the client and for
-which the transition effects are required. When a handle matches, the render
-stage performs the transition effect. When the handle does not match, the
-render stage passes the drawing operations straight through to the next render
-stage in the chain. </p> <p>The following code snippet shows how to retrieve
-a window's handle from the <xref href="GUID-7837D4F3-4BF4-344B-B987-6789060553B3.dita"><apiname>MWsWindowTreeNode</apiname></xref> object returned
-by the <codeph>MWsDrawAnnotationObserver</codeph> functions: </p> <codeblock id="GUID-156D0D65-0746-5FED-BB8F-8188D6B2C7F7" xml:space="preserve">windowID = aWindowTreeNode.Window-&gt;Handle();</codeblock> <p> <i>Note</i>:
-Communication of the window handle from the client to the render stage is
-beyond the scope of this documentation. </p> </li>
-</ul> </section>
-<section id="GUID-6EC4AF69-61E8-475A-9D87-3E0B5634E173"><title>MWsWindowVisibilityNotifier</title> <p> <xref href="GUID-FF3EE463-E775-3948-B1EB-66135E24A623.dita"><apiname>MWsWindowVisibilityNotifier</apiname></xref> is
-an optional interface that enables a render stage to communicate changes in
-the visibility of windows and other nodes in the window tree to the Window
-Server. A render stage that works in <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">change-tracking
-rendering mode</xref> must implement this interface. </p> <p>When the Window
-Server is in its default dirty-rectangle tracking mode, it tracks which windows
-are visible and sends visibility-changed events to clients, Content Rendering
-Plug-ins (CRPs) and animation plug-ins. This enables these clients to know
-when their windows are visible and therefore need to draw or animate, and
-when they are obscured and do not need to draw or animate. This means that
-CPU cycles are not wasted producing animations when they are not visible and
-ensures that animations run when they are visible. </p> <p>When the Window
-Server is in change-tracking mode, it does not track the visible regions and
-tracking of visible regions is delegated to the render stage. At the minimum,
-the render stage must set the visible region to be the whole window or none
-of it. </p> <p>The Window Server implements the <xref href="GUID-9CF4DEE1-57D8-3F57-93B2-6EB701262AD7.dita"><apiname>MWsWindowVisibilityObserver</apiname></xref> interface
-through which it responds to visibility change notifications sent by the render
-stage. </p> </section>
-<section id="GUID-5CDE2713-4CBD-4B35-A10F-A599B7C4EC55"><title>MWsDisplayControl</title> <p> <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> is
-the interface for controlling the display configuration. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
-Stage Display Control and Mapping</xref> for more information. </p> </section>
-<section id="GUID-D35742C7-B61F-417F-9EA0-9B07633FBBBC"><title>MWsDisplayMapping</title> <p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> is
-the interface for mapping between coordinate spaces. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
-Stage Display Control and Mapping</xref> for more information. </p> </section>
-<section id="GUID-95E80D04-3A9F-4657-AB94-1F3AF5048AB2"><title>MWsDisplayPolicy</title> <p> <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is
-an optional interface, which if implemented, determines the UI to composition
-mapping policy. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
-Stage Display Control and Mapping</xref> for more information. </p> </section>
-</conbody><related-links>
-<link href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita"><linktext>Render Stage
-Overview</linktext></link>
-<link href="GUID-309B01B6-F74A-5EF0-B225-702BF8814847.dita"><linktext>TFX Render
-Stage                 Examples</linktext></link>
-<link href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita"><linktext>Display 
-               Control and Mapping</linktext></link>
-<link href="GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7.dita"><linktext>Creating
-a Render Stage                 Plug-in</linktext></link>
-<link href="GUID-41802B91-26B3-5F3C-AE04-B6954F3804B7.dita"><linktext>Scene Elements</linktext>
-</link>
-<link href="GUID-D76C7759-739D-5C98-B718-7297687FE630.dita"><linktext>Extended
-Bitmaps</linktext></link>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"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: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336" xml:lang="en"><title>Render
+Stage Interfaces</title><shortdesc>This topic builds on the Render Stages Overview and provides an
+introduction to the main render stage interfaces. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
+audience</b>: Device creators. </p>
+<p>The <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages
+Overview</xref> introduced some of the interfaces that render stages implement.
+Here we will look at those in more detail, along with some of the other interfaces. </p>
+<section id="GUID-48000875-54A6-4563-8FC0-86320EA69D2C"><title>MWsObjectProvider</title> <p> <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> is
+a Window Server plug-in framework interface, which provides a mechanism through
+which classes can offer extension interfaces. Render stages and most of the
+related classes implement this interface. </p> </section>
+<section id="GUID-06DE55A6-6346-4F78-8F4A-320F15ADB822"><title>CWsRenderStage</title> <p> <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita"><apiname>CWsRenderStage</apiname></xref> is
+an abstract class that all render stages must derive from. It has two pure
+virtual functions: <codeph>Begin()</codeph> and <codeph>End()</codeph>, which
+must be implemented in the concrete class. </p> <p>The Window Server's output
+to the render stage pipeline is not a continuous stream, but instead consists
+of batches of drawing operations. When client drawing or server-side animations
+require a screen update, the <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">Window
+Server rendering loop</xref> schedules a redraw. When this redraw occurs,
+a batch of drawing operations is produced to perform the updates. </p> <p>The
+Window Server calls <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita#GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A/GUID-75503F6F-91DA-3392-8CD5-34FFF9095D30"><apiname>CWsRenderStage::Begin()</apiname></xref> at the beginning
+of a batch of draw operations. This gives the render stages an opportunity
+to perform any preparation. Similarly the Window Server calls <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita#GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A/GUID-0EBA06BF-D17F-3485-85B6-F4B855A48B62"><apiname>CWsRenderStage::End()</apiname></xref> at
+the end of the batch, which provides the render stages with the opportunity
+to perform any tidying up. </p> <p>For example, a flicker buffer render stage
+might use the <codeph>Begin()</codeph> call as a signal to clear its off-screen
+buffer, and the <codeph>End()</codeph> call as a signal to perform the blit
+of the accumulated updates to the next render stage. The final render stage
+might use the <codeph>End()</codeph> call as the signal to submit a surface
+update to the composition engine. </p> <p>Render stages perform all rendering
+operations between the <codeph>Begin()</codeph> and <codeph>End()</codeph> calls.
+The Window Server calls the <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> functions
+only between the <codeph>Begin()</codeph> and <codeph>End()</codeph> calls.
+The render stage could <codeph>ASSERT</codeph> that these functions are not
+called at other times and ignore them if they are or take some other action
+as appropriate. However, render stages can safely call composition context
+functions outside the <codeph>Begin()</codeph> and <codeph>End()</codeph> calls.
+In addition, the <xref href="GUID-B1E048A2-D5E8-3E7F-A6AC-6B8F3ED3067C.dita"><apiname>MWsScreenDevice</apiname></xref> functions may be called
+at any time. </p> </section>
+<section id="GUID-B189C7EB-AD1F-51C6-91F1-8EBD49D8F69D"><title>MWsGraphicsContext</title> <p> <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> is
+the interface for GDI-like drawing. The Window Server requests this interface
+from the first render stage in the chain using the object provider mechanism.
+This is a mandatory interface, which means that a render stage must not return
+null when it receives an object provider request for this interface. However,
+providing an implementation is not mandatory. For example, a logging render
+stage might simply delegate to the next render stage instead of returning
+its own implementation of this interface. </p> <p>The member functions correspond
+to functions in <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref> (such as <codeph>DrawText()</codeph> and <codeph>BitBlt()</codeph>)
+but without functions that are not suitable for hardware acceleration (such
+as read-modify-write functions like <codeph>SetFaded()</codeph>). </p> <p>The
+final render stage in the chain typically provides an implementation of <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> in
+terms of a concrete rendering context—for example, by translating into BitGDI
+or OpenVG calls. </p> <p>If <b>extended bitmaps</b> are supported on the device,
+the implementation of the functions that receive a <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> as
+an argument can check whether it is the handle to an extended bitmap. If it
+is, the render stage can process the proprietary data within the bitmap. You
+can get access to the proprietary data by using <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-2AB943ED-7DBE-3FDA-82AF-317F152EDB03"><apiname>CFbsBitmap::DataAddress()</apiname></xref>.
+Here is a simple example: </p> <codeblock id="GUID-390E236B-7EB1-5A90-B1F5-A0190403FF27" xml:space="preserve">// bmp points to a bitmap to be drawn.
+TUid type = bmp-&gt;ExtendedBitmapType();
+    
+if (type==KUidMyProprietaryFormat)
+    {    
+    bmp-&gt;BeginDataAccess();
+    const TUint32* data = bmp-&gt;DataAddress();
+    TInt dataSize = bmp-&gt;DataSize();
+    ProcessMyData(data, dataSize);
+    bmp-&gt;EndDataAccess(ETrue);
+    }
+</codeblock> <p>For some data formats, particularly those that contain vector
+data, such as SVG, this approach has advantages compared to letting the extended
+bitmap rasterizer DLL process the proprietary data. For example, the extended
+bitmap rasterizer DLL rasterizes the proprietary data into a pixel buffer,
+which is then blitted to the screen. In contrast the render stage can insert
+the drawing commands directly into the drawing command stream without the
+use of intermediate pixel buffers. In addition, unlike the extended bitmap
+rasterizer DLL, the render stage does not need to rasterize the image to a
+higher resolution in order to scale it down. The use of the render stage to
+process the proprietary data can therefore potentially save memory and improve
+performance, depending on the data format. </p> <p>Although the Symbian Foundation
+does not currently provide extended bitmap functionality in the main render
+stages, it does provide a test extended bitmap render stage. You can use this
+as an example when you implement your own extended bitmap functionality. </p> <p>For
+more information, see <xref href="GUID-D76C7759-739D-5C98-B718-7297687FE630.dita">Extended
+Bitmaps</xref>. </p> </section>
+<section id="GUID-490A69C0-E8F0-4767-965E-798C5953A8D9"><title>MWsScene </title> <p> <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> is the composition
+context interface for use with <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
+composition</xref>. It is a mandatory interface. However, like <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref>,
+some render stages might simply delegate to the next render stage rather than
+providing their own implementations. The final render stage in the chain typically
+provides an implementation of <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> in terms of OpenWF-C. </p> <p>The <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> interface
+defines the composition context for a particular screen (or an off-screen
+buffer representing the screen) in terms of a collection of rectangular regions.
+These are called <xref href="GUID-41802B91-26B3-5F3C-AE04-B6954F3804B7.dita">scene
+elements</xref> or simply <b>elements</b>. Each one is represented by the <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> interface.
+The <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> interface manages the relative ordinal positions
+of the elements and uses the elements to track external surfaces and their
+place in the composition scene. Render stages can manipulate element metadata
+in order to perform transition effects and use the hardware-accelerated composition
+facilities provided by OpenWF-C to perform transition effects (such as slide,
+zoom and fade). </p> <p>Some of the key functions are: </p> <ul>
+<li id="GUID-8265EB9F-14A5-54C5-B3EB-3925964121A5"><p> <codeph>CreateSceneElementL()</codeph>.
+Creates a new element for use in the scene. After creation, an element is
+available to the caller but <codeph>InsertSceneElement()</codeph> must be
+called to actually insert it into the pending scene. </p> </li>
+<li id="GUID-8736EC49-0C43-58AB-B9F1-397D2B7D6486"><p> <codeph>InsertSceneElement()</codeph>.
+Inserts an element into the scene. </p> </li>
+<li id="GUID-9016ACE1-E1BC-5126-A7D8-8A564CF96865"><p> <codeph>RemoveSceneElement()</codeph>.
+Removes an element from the scene. </p> </li>
+<li id="GUID-832568D5-4DCD-59CF-9982-2C6584AFC2B9"><p> <codeph>DestroySceneElement()</codeph>.
+Destroys an element and removes its resources from the scene. </p> </li>
+<li id="GUID-BA1D1346-EE28-5179-BBC9-300618162607"><p> <codeph>ComposePendingScene()</codeph>.
+Renders the pending scene to an off-screen target. </p> </li>
+<li id="GUID-AF8EFE14-B829-5B4B-998E-3CF161F027C1"><p> <codeph> RegisterSurface()</codeph>.
+Marks a surface as potentially in use beyond its lifetime within the scene.
+There are two typical use cases—one is where the contents of the surface (for
+example, a video frame) must be maintained when users switch to another application
+that hides the surface so that it is no longer part of the scene. This means
+that users can have a seamless experience when they switch back to the video.
+The other use case is where the content of a surface needs to be populated
+before it is attached to a window and therefore added to the scene. </p> </li>
+<li id="GUID-CE8BB038-0B65-5C78-B457-F7B532471826"><p> <codeph>UnregisterSurface()</codeph>.
+Marks the surface as no longer in use beyond its inclusion in the scene. </p> </li>
+</ul> <p>Any updates to the scene introduced by the render stage (such as
+adding a new element) are pending until the Window Server calls <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita#GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A/GUID-0EBA06BF-D17F-3485-85B6-F4B855A48B62"><apiname>CWsRenderStage::End()</apiname></xref> to
+commit the scene. </p> </section>
+
+<section id="GUID-2924C0EE-222B-4A23-830B-DD31A985C13F"><title>MWsElement</title> <p> <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> is a
+mandatory interface for managing scene elements when <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
+composition</xref> is in use. This interface is obtained by using <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-B776F464-8AAE-32C4-A0FF-026D8E553B7D"><apiname>MWsScene::CreateSceneElementL()</apiname></xref> rather
+than the object provider mechanism. </p> <p>The <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> interface
+provides a way of associating metadata with an image source. From the render
+stage's point of view, the image source is a surface that is connected to
+the element—whereas OpenWF-C has the concept of image sources that are created
+from native streams. Because the <xref href="GUID-83510B5B-9725-5272-BF51-23A089178DAC.dita">OpenWF-C
+Support component</xref> implements native streams in terms of Symbian surfaces,
+the render stage can ignore this distinction and simply cast the address of
+the <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref> to the OpenWF-C native stream type (<xref href="GUID-DF6DF530-EC4E-32D4-9CC8-536F3F2BE83E.dita"><apiname>WFCNativeStreamType</apiname></xref>). </p> <p>The
+element metadata includes the following: </p> <ul>
+<li id="GUID-BD2BD787-B90D-5E00-A533-7401CB4A7CB4"><p>Source rectangle—the
+region within the surface from which pixels are taken. This enables the surface
+to be cropped and is equivalent to the surface viewport described in <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External Surfaces Overview</xref>. </p> </li>
+<li id="GUID-CFD9C7F9-78EA-5719-A5F1-DD2D78ECFEE8"><p>Destination rectangle—the
+target rectangle in the composition output to which the pixels are rendered.
+This is equivalent to the extent. </p> </li>
+<li id="GUID-9EE4ECD3-7274-553B-8123-250EE3E7751A"><p>Global alpha—a global
+alpha value for use in blending the surface into the composition output. </p> </li>
+<li id="GUID-1FA2DF2A-2FBC-551B-B4D9-6D6711F46D39"><p>Source rotation—the
+number of quadrant angles by which the contents of the surface are rotated. </p> </li>
+<li id="GUID-3830D1D3-8687-5C7A-B886-F1B0CED6BF26"><p>Source flipping—a Boolean
+value that indicates whether the contents of the surface are flipped. </p> </li>
+<li id="GUID-7535C9D7-314C-5EF6-8D50-226DC5F2DE33"><p>Target renderer flags—these
+provide information to the rendering subsystem (for example, the OpenWF-C
+engine), such as whether the renderer should blend based on the global alpha
+value or the alpha channel in the surface itself. </p> </li>
+<li id="GUID-8B50BD6E-5F9A-5690-99CC-73AE8D129B52"><p>Render stage flags—these
+provide information to the render stages, such as whether the UI surface is
+always on top. </p> </li>
+</ul> </section>
+
+<section id="GUID-4A3F1B94-9EFE-47EE-A060-FAB8E92D3F3C"><title>MWsScreenDevice</title> <p> <xref href="GUID-B1E048A2-D5E8-3E7F-A6AC-6B8F3ED3067C.dita"><apiname>MWsScreenDevice</apiname></xref> is
+the interface for managing the screen. It provides functions for controlling
+rotation and fetching data from the screen such as a screen snapshot. </p> </section>
+<section id="GUID-3558E65B-F8C9-4A63-B22E-41B7E2ECB21D"><title>MWsTextCursor</title> <p> <xref href="GUID-F43CBB9C-238B-33C5-B872-AAE0104F047E.dita"><apiname>MWsTextCursor</apiname></xref> is
+an interface that enables render stages to implement a text cursor to represent
+the flashing bar or rectangle that represents the current position when editing
+text. </p> <p>Prior to the introduction of ScreenPlay text cursors were drawn
+using XOR drawing because it provides high contrast against the background.
+Render stages can implement this interface using the same approach but it
+is generally inefficient on hardware-accelerated platforms. Therefore another
+approach, such as a drop shadow or sprite, might be preferable. </p> <p>The
+preferred solution is that clients use <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-684910B9-CCEA-3798-BE23-967820BBF363"><apiname>RWsSession::SetCustomTextCursor()</apiname></xref> to
+replace the text cursor with a sprite. This means that user themes can use
+a sprite that matches the text—for example, a white sprite with white text
+and a black sprite with black text. If a client does this, the render stage’s <xref href="GUID-F43CBB9C-238B-33C5-B872-AAE0104F047E.dita"><apiname>MWsTextCursor</apiname></xref> API
+is not used when drawing text cursors for that client. Instead, the text cursor
+sprite is drawn using GDI draw operations through the <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> interface. </p> </section>
+<section id="GUID-6D6482E9-7AD7-46A1-AFFB-B98B6BAB1973"><title>MWsFader</title> <p> <xref href="GUID-1CF41CFD-27C8-39D7-A615-18CE765436DE.dita"><apiname>MWsFader</apiname></xref> is the interface
+for providing fading capabilities. </p> </section>
+<section id="GUID-EDE3C8A9-1EBB-4B8C-A483-1F469A19CCB5"><title>MWsWindowTreeObserver</title> <p> <xref href="GUID-028CC583-AC32-3D60-943A-A80F84E05DD2.dita"><apiname>MWsWindowTreeObserver</apiname></xref> is
+an optional interface that enables a render stage to create a replica of the
+window tree, known as the <b>visuals tree</b>. The Window Server uses this
+interface to tell the render stage about the window tree structure and changes
+to window tree nodes. Note that this interface considers animations and sprites
+to be nodes in the window tree. </p> <p>See the <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita#GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87/GUID-5D81D1A7-26A0-5461-9AC5-3EF359D283CB">Advanced
+Use Case</xref> section of the <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render
+Stages Overview</xref> for more information. </p> </section>
+<section id="GUID-7536F610-F9F7-5E17-82D8-623D774DC091"><title>MWsDrawAnnotationObserver</title> <p> <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita"><apiname>MWsDrawAnnotationObserver</apiname></xref> is
+an optional interface that enables render stages to associate a batch of drawing
+operations with a specific window or node in the visuals tree. TFX render
+stages generally need to implement this interface. </p> <p>If the render stage
+implements the <xref href="GUID-028CC583-AC32-3D60-943A-A80F84E05DD2.dita"><apiname>MWsWindowTreeObserver</apiname></xref> interface, implementing
+the <codeph>MWsDrawAnnotationObserver</codeph> interface enables the render
+stage to know which node in the visuals tree each batch of drawing operations
+belongs to. This means that the render stage can associate the batch with
+the correct window, sprite or other element in the visuals tree and manage
+it efficiently. </p> <p>If the render stage does <b>not</b> implement the <codeph>MWsWindowTreeObserver</codeph> interface,
+the <codeph>MWsDrawAnnotationObserver</codeph> interface still provides the
+window tree node pointers for each batch of drawing operations. There are
+two different approaches this type of render stage can take: </p> <ul>
+<li id="GUID-3248DECC-4F1E-5504-AC00-751D33D032A5"><p>The render stage can
+treat the window tree node pointers as unique identifiers for the windows.
+This approach is typically used when the Window Server's default <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">dirty-rectangle
+rendering mode</xref> is in use. In this mode the Window Server sends the
+batches of drawing operations to the first render stage in back to front z-order.
+(That is, the drawing operations for the windows in the background come before
+the drawing operations for the windows at the front.) Using the unique identifier
+and the z-order, the render stage can identify new windows that are at the
+top and slide them on or perform some other transition effect. </p> <p>This
+approach is suitable when the render stage always performs the same transition
+effect. For example, the render stage slides on all new windows that are at
+the front. </p> </li>
+<li id="GUID-F21BC536-DE1C-585C-B183-AF499AC31FC6"><p>The other approach is
+suitable when the render stage applies transition effects to specific windows;
+for example, windows that belong to a media player application. In this scenario,
+the client communicates the handles of those windows to the render stage.
+The render stage uses the <codeph>MWsDrawAnnotationObserver</codeph> to retrieve
+the handles of the windows to which the drawing operations relate. The render
+stage compares these handles with those communicated by the client and for
+which the transition effects are required. When a handle matches, the render
+stage performs the transition effect. When the handle does not match, the
+render stage passes the drawing operations straight through to the next render
+stage in the chain. </p> <p>The following code snippet shows how to retrieve
+a window's handle from the <xref href="GUID-7837D4F3-4BF4-344B-B987-6789060553B3.dita"><apiname>MWsWindowTreeNode</apiname></xref> object returned
+by the <codeph>MWsDrawAnnotationObserver</codeph> functions: </p> <codeblock id="GUID-156D0D65-0746-5FED-BB8F-8188D6B2C7F7" xml:space="preserve">windowID = aWindowTreeNode.Window-&gt;Handle();</codeblock> <p> <i>Note</i>:
+Communication of the window handle from the client to the render stage is
+beyond the scope of this documentation. </p> </li>
+</ul> </section>
+<section id="GUID-6EC4AF69-61E8-475A-9D87-3E0B5634E173"><title>MWsWindowVisibilityNotifier</title> <p> <xref href="GUID-FF3EE463-E775-3948-B1EB-66135E24A623.dita"><apiname>MWsWindowVisibilityNotifier</apiname></xref> is
+an optional interface that enables a render stage to communicate changes in
+the visibility of windows and other nodes in the window tree to the Window
+Server. A render stage that works in <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">change-tracking
+rendering mode</xref> must implement this interface. </p> <p>When the Window
+Server is in its default dirty-rectangle tracking mode, it tracks which windows
+are visible and sends visibility-changed events to clients, Content Rendering
+Plug-ins (CRPs) and animation plug-ins. This enables these clients to know
+when their windows are visible and therefore need to draw or animate, and
+when they are obscured and do not need to draw or animate. This means that
+CPU cycles are not wasted producing animations when they are not visible and
+ensures that animations run when they are visible. </p> <p>When the Window
+Server is in change-tracking mode, it does not track the visible regions and
+tracking of visible regions is delegated to the render stage. At the minimum,
+the render stage must set the visible region to be the whole window or none
+of it. </p> <p>The Window Server implements the <xref href="GUID-9CF4DEE1-57D8-3F57-93B2-6EB701262AD7.dita"><apiname>MWsWindowVisibilityObserver</apiname></xref> interface
+through which it responds to visibility change notifications sent by the render
+stage. </p> </section>
+<section id="GUID-5CDE2713-4CBD-4B35-A10F-A599B7C4EC55"><title>MWsDisplayControl</title> <p> <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> is
+the interface for controlling the display configuration. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
+Stage Display Control and Mapping</xref> for more information. </p> </section>
+<section id="GUID-D35742C7-B61F-417F-9EA0-9B07633FBBBC"><title>MWsDisplayMapping</title> <p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> is
+the interface for mapping between coordinate spaces. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
+Stage Display Control and Mapping</xref> for more information. </p> </section>
+<section id="GUID-95E80D04-3A9F-4657-AB94-1F3AF5048AB2"><title>MWsDisplayPolicy</title> <p> <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is
+an optional interface, which if implemented, determines the UI to composition
+mapping policy. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
+Stage Display Control and Mapping</xref> for more information. </p> </section>
+</conbody><related-links>
+<link href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita"><linktext>Render Stage
+Overview</linktext></link>
+<link href="GUID-309B01B6-F74A-5EF0-B225-702BF8814847.dita"><linktext>TFX Render
+Stage                 Examples</linktext></link>
+<link href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita"><linktext>Display 
+               Control and Mapping</linktext></link>
+<link href="GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7.dita"><linktext>Creating
+a Render Stage                 Plug-in</linktext></link>
+<link href="GUID-41802B91-26B3-5F3C-AE04-B6954F3804B7.dita"><linktext>Scene Elements</linktext>
+</link>
+<link href="GUID-D76C7759-739D-5C98-B718-7297687FE630.dita"><linktext>Extended
+Bitmaps</linktext></link>
 </related-links></concept>
\ No newline at end of file