--- a/Symbian3/PDK/Source/GUID-309B01B6-F74A-5EF0-B225-702BF8814847.dita Fri Jul 02 12:51:36 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-309B01B6-F74A-5EF0-B225-702BF8814847.dita Fri Jul 16 17:23:46 2010 +0100
@@ -11,8 +11,8 @@
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-309B01B6-F74A-5EF0-B225-702BF8814847"><title>TFX Render Stage Examples</title><shortdesc>This topic provides examples of how a transition effect (TFX) render stage can perform simple transitions in the ScreenPlay variant. Note that the APIs are different in the non-ScreenPlay variant. </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>This example assumes a render stage configuration that consists of two render stage plug-ins—the first in the chain is a transition effect (TFX) engine and the second and final one displays the results on the screen. The TFX render stage does <b>not</b> implement a visuals tree and visuals stores. The configuration matches that shown in the <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita#GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87/GUID-E225354D-1EFC-513E-843E-42528C3FCCCF">Typical Use Case</xref> section of the <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages Overview</xref>. </p> <p>The TFX render stage creates a TFX surface for its own use—for example, to capture drawing for use in transition effects. It can then introduce parts of the TFX surface into the composition scene as required. </p> <section><title>A window slides on from the side</title> <p>First we will consider what happens when a window slides onto the view from the side. </p> <fig id="GUID-CDB60D24-DB1B-563D-A272-FC61B245A60F"><title>
A window slides onto the screen from the side
- </title> <image href="GUID-60AB43B9-29B1-5BAC-B70A-617C279321C1_d0e244335_href.png" placement="inline"/></fig> <p>We will assume that the window does not have an external surface attached. However, it could have semi-transparent pixels and the background scene could have an external surface attached. The transition effect is performed by capturing the window pixels to the TFX surface, and then using composition operations to make the TFX surface (containing the window pixels) slide on from the side. In particular, no updates to the TFX surface or UI surface are required during the transition—everything is done with element updates. The following sequence diagram shows the high-level steps involved in setting up and performing the transition effect. </p> <fig id="GUID-36EA4E85-8A52-5F18-A8E4-EEBDC069A92B"><title>
+ </title> <image href="GUID-60AB43B9-29B1-5BAC-B70A-617C279321C1_d0e250346_href.png" placement="inline"/></fig> <p>We will assume that the window does not have an external surface attached. However, it could have semi-transparent pixels and the background scene could have an external surface attached. The transition effect is performed by capturing the window pixels to the TFX surface, and then using composition operations to make the TFX surface (containing the window pixels) slide on from the side. In particular, no updates to the TFX surface or UI surface are required during the transition—everything is done with element updates. The following sequence diagram shows the high-level steps involved in setting up and performing the transition effect. </p> <fig id="GUID-36EA4E85-8A52-5F18-A8E4-EEBDC069A92B"><title>
Window slide-on sequence diagram
- </title> <image href="GUID-F58C17D1-3834-5DEB-8B8B-52CD81AA9BF4_d0e244344_href.png" placement="inline"/></fig> <p>The main points to note are: </p> <ul><li id="GUID-753FF6D5-8BAF-5F29-9CF9-13B3158E510C"><p>The <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita#GUID-21240143-D578-3114-9836-F765F70A987C/GUID-00C6BB2C-E6DB-366A-B926-32FA90FB6CC2"><apiname>MWsDrawAnnotationObserver::WindowRedrawStart</apiname></xref> and <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita#GUID-21240143-D578-3114-9836-F765F70A987C/GUID-8BA29084-F20C-363D-8A25-39E445DE22B0"><apiname>MWsDrawAnnotationObserver::WindowRedrawEnd</apiname></xref> methods enable the TFX render stage to associate drawing operations with windows. When a window requires TFX, the render stage captures its drawing operations onto the TFX surface, while letting all other drawing pass through to the UI surface. See <xref href="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita#GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336/GUID-7536F610-F9F7-5E17-82D8-623D774DC091">MWsDrawAnnotationObserver</xref> for more information. </p> </li> <li id="GUID-FA3A56C9-F906-5013-B047-53FF3415D690"><p>The TFX render stage calls <xref href="GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704.dita#GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704/GUID-251E3B0E-DA5A-32FC-9253-B4960C8C8A6D"><apiname>MWsScreenRedraw::ScheduleRender()</apiname></xref> in order to ensure that it is called again after a short interval. It also does this repeatedly while performing the transition effect, although this is not shown on the diagram. </p> </li> <li id="GUID-EBE11E85-00F4-5FB3-A717-1FB749438418"><p>The TFX render stage introduces the TFX surface into the composition scene by calling <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-3E35F2A4-548C-3C9E-A1B2-3C7EBD50EFAB"><apiname>MWsScene::InsertSceneElement()</apiname></xref>. </p> </li> <li id="GUID-FBC5934D-9FCD-58D6-8836-C7516AD7C51C"><p>The TFX render stage achieves the transition effect by successively updating the element metadata of the TFX surface to move it across the scene. </p> </li> <li id="GUID-DD960043-9B79-58BA-B312-0881DFD4285A"><p>When the transition effect is finished, the TFX render stage blits the window pixels from the TFX surface into their final position in the UI surface. For semi-transparent windows this must be synchronized with the removal of the TFX surface from the scene—by <codeph>Begin()</codeph> and <codeph>End()</codeph> calls—otherwise the semi-transparent content would be blended twice. This is not an issue for opaque windows. </p> </li> </ul> </section> <section><title>Full screen slide-on transition </title> <p>Now we will consider what happens when the user switches between two views, A and B. The transition slides A off to one side while B slides on from the other side. </p> <fig id="GUID-5E2124F8-4FDD-57BB-A1D9-1E17922229DE"><title>
+ </title> <image href="GUID-F58C17D1-3834-5DEB-8B8B-52CD81AA9BF4_d0e250355_href.png" placement="inline"/></fig> <p>The main points to note are: </p> <ul><li id="GUID-753FF6D5-8BAF-5F29-9CF9-13B3158E510C"><p>The <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita#GUID-21240143-D578-3114-9836-F765F70A987C/GUID-00C6BB2C-E6DB-366A-B926-32FA90FB6CC2"><apiname>MWsDrawAnnotationObserver::WindowRedrawStart</apiname></xref> and <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita#GUID-21240143-D578-3114-9836-F765F70A987C/GUID-8BA29084-F20C-363D-8A25-39E445DE22B0"><apiname>MWsDrawAnnotationObserver::WindowRedrawEnd</apiname></xref> methods enable the TFX render stage to associate drawing operations with windows. When a window requires TFX, the render stage captures its drawing operations onto the TFX surface, while letting all other drawing pass through to the UI surface. See <xref href="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita#GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336/GUID-7536F610-F9F7-5E17-82D8-623D774DC091">MWsDrawAnnotationObserver</xref> for more information. </p> </li> <li id="GUID-FA3A56C9-F906-5013-B047-53FF3415D690"><p>The TFX render stage calls <xref href="GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704.dita#GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704/GUID-251E3B0E-DA5A-32FC-9253-B4960C8C8A6D"><apiname>MWsScreenRedraw::ScheduleRender()</apiname></xref> in order to ensure that it is called again after a short interval. It also does this repeatedly while performing the transition effect, although this is not shown on the diagram. </p> </li> <li id="GUID-EBE11E85-00F4-5FB3-A717-1FB749438418"><p>The TFX render stage introduces the TFX surface into the composition scene by calling <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-3E35F2A4-548C-3C9E-A1B2-3C7EBD50EFAB"><apiname>MWsScene::InsertSceneElement()</apiname></xref>. </p> </li> <li id="GUID-FBC5934D-9FCD-58D6-8836-C7516AD7C51C"><p>The TFX render stage achieves the transition effect by successively updating the element metadata of the TFX surface to move it across the scene. </p> </li> <li id="GUID-DD960043-9B79-58BA-B312-0881DFD4285A"><p>When the transition effect is finished, the TFX render stage blits the window pixels from the TFX surface into their final position in the UI surface. For semi-transparent windows this must be synchronized with the removal of the TFX surface from the scene—by <codeph>Begin()</codeph> and <codeph>End()</codeph> calls—otherwise the semi-transparent content would be blended twice. This is not an issue for opaque windows. </p> </li> </ul> </section> <section><title>Full screen slide-on transition </title> <p>Now we will consider what happens when the user switches between two views, A and B. The transition slides A off to one side while B slides on from the other side. </p> <fig id="GUID-5E2124F8-4FDD-57BB-A1D9-1E17922229DE"><title>
Full screen slide-on transition
- </title> <image href="GUID-26D1E607-C63F-5A2D-9482-2A9A85F466C8_d0e244413_href.png" placement="inline"/></fig> <p>First we will assume that neither A nor B has an external surface. The transition effect is performed in a similar way to the window transition described earlier. The outgoing view is captured into the TFX surface, and introduced as the topmost element into the composition scene. One complication is that on the client side, the outgoing and incoming views may run in different processes. The transition engine must therefore wait for A's exit and B's entry to be signaled before it performs the transition effect. </p> <p>As in the previous example, the actors are the client application, the Window Server and the two render stages. The system boundary is the Window Server process. Assuming that view A is currently present in the UI surface, the basic flow is as follows: </p> <ol id="GUID-5B62EE78-068F-56D2-BC56-7A1DE0ECB70C"><li id="GUID-02486331-EDE3-5C13-A443-9F7EEA1527EC"><p>View A signals the start and end of its exit transition. </p> </li> <li id="GUID-ED5A72A0-94E3-5630-AAD6-9EA1B944133A"><p>View B signals the start of its entry transition. </p> </li> <li id="GUID-8D593EEA-E247-5AC7-8368-09B916FA8129"><p>View B issues new drawing operations to the Window Server. </p> </li> <li id="GUID-285E79CB-EF1D-512B-BAF8-5B7AE69C2260"><p>View B calls <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B431DC60-D11F-3239-8F52-4257B9B0E0C9"><apiname>RWsSession::Finish()</apiname></xref>. </p> </li> <li id="GUID-589B198C-52A5-58B2-AB49-6917749EF768"><p>The Window Server lower loop runs. </p> </li> <li id="GUID-6F012760-5FBC-5BE5-A483-54245374E9E8"><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> on the TFX render stage. </p> </li> <li id="GUID-EC87DA51-437F-5B65-9645-61C72BE769BE"><p>The TFX render stage introduces the TFX surface as the topmost surface in the composition scene, and moves the UI surface off to the side of the scene. It does this by calling <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-3E35F2A4-548C-3C9E-A1B2-3C7EBD50EFAB"><apiname>MWsScene::InsertSceneElement()</apiname></xref> and then performing the <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> updates for the UI surface. </p> </li> <li id="GUID-D7A59885-D8AB-5BFD-B569-CD0E839DDF8D"><p>The Window Server lower loop uses <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> calls to issue the draw operations for view B. </p> </li> <li id="GUID-BC743329-8170-5EC2-A3F7-B381FAA1FB81"><p>The TFX render stage passes the draw operations straight through to the display render stage, which renders them into the UI surface. However, this is not visible in the composition scene, because it is obscured by the TFX surface. </p> </li> <li id="GUID-ED77E906-6330-567C-B17D-5D66E0A53521"><p>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>. </p> </li> <li id="GUID-1B3F15B1-4DC6-5164-A93B-2F33F1D60064"><p>The TFX render stage calls <xref href="GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704.dita#GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704/GUID-251E3B0E-DA5A-32FC-9253-B4960C8C8A6D"><apiname>MWsScreenRedraw::ScheduleRender()</apiname></xref>, to ensure that it is called again after a short interval. </p> </li> <li id="GUID-F091535F-208E-57B3-9787-593B7C21039B"><p>The client application signals the end of the entry transition and the Window Server scheduler fires. </p> </li> <li id="GUID-B1A48A62-9527-5653-8C20-02E35CF83966"><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> and <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> on the TFX render stage, but without any drawing, giving it the opportunity to run. </p> </li> <li id="GUID-FC40FDEA-F232-5FE9-97F4-37E82B9ACAD9"><p>Over a series of frames, the TFX render stage modifies the element metadata to make the TFX surface (containing view A) slide off, and the UI surface (containing view B) slide on. It does this by updating the elements using <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> calls. </p> </li> <li id="GUID-4A2F9221-FA8B-5943-946A-4633D6124501"><p>When the transition is finished, the TFX render stage removes the TFX surface from composition scene, by calling <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-F6AE7CF1-0B56-3243-9E45-1C7A9E49DB83"><apiname>MWsScene::RemoveSceneElement()</apiname></xref>. </p> </li> </ol> </section> </conbody><related-links><link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext> </link> </related-links></concept>
\ No newline at end of file
+ </title> <image href="GUID-26D1E607-C63F-5A2D-9482-2A9A85F466C8_d0e250424_href.png" placement="inline"/></fig> <p>First we will assume that neither A nor B has an external surface. The transition effect is performed in a similar way to the window transition described earlier. The outgoing view is captured into the TFX surface, and introduced as the topmost element into the composition scene. One complication is that on the client side, the outgoing and incoming views may run in different processes. The transition engine must therefore wait for A's exit and B's entry to be signaled before it performs the transition effect. </p> <p>As in the previous example, the actors are the client application, the Window Server and the two render stages. The system boundary is the Window Server process. Assuming that view A is currently present in the UI surface, the basic flow is as follows: </p> <ol id="GUID-5B62EE78-068F-56D2-BC56-7A1DE0ECB70C"><li id="GUID-02486331-EDE3-5C13-A443-9F7EEA1527EC"><p>View A signals the start and end of its exit transition. </p> </li> <li id="GUID-ED5A72A0-94E3-5630-AAD6-9EA1B944133A"><p>View B signals the start of its entry transition. </p> </li> <li id="GUID-8D593EEA-E247-5AC7-8368-09B916FA8129"><p>View B issues new drawing operations to the Window Server. </p> </li> <li id="GUID-285E79CB-EF1D-512B-BAF8-5B7AE69C2260"><p>View B calls <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B431DC60-D11F-3239-8F52-4257B9B0E0C9"><apiname>RWsSession::Finish()</apiname></xref>. </p> </li> <li id="GUID-589B198C-52A5-58B2-AB49-6917749EF768"><p>The Window Server lower loop runs. </p> </li> <li id="GUID-6F012760-5FBC-5BE5-A483-54245374E9E8"><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> on the TFX render stage. </p> </li> <li id="GUID-EC87DA51-437F-5B65-9645-61C72BE769BE"><p>The TFX render stage introduces the TFX surface as the topmost surface in the composition scene, and moves the UI surface off to the side of the scene. It does this by calling <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-3E35F2A4-548C-3C9E-A1B2-3C7EBD50EFAB"><apiname>MWsScene::InsertSceneElement()</apiname></xref> and then performing the <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> updates for the UI surface. </p> </li> <li id="GUID-D7A59885-D8AB-5BFD-B569-CD0E839DDF8D"><p>The Window Server lower loop uses <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> calls to issue the draw operations for view B. </p> </li> <li id="GUID-BC743329-8170-5EC2-A3F7-B381FAA1FB81"><p>The TFX render stage passes the draw operations straight through to the display render stage, which renders them into the UI surface. However, this is not visible in the composition scene, because it is obscured by the TFX surface. </p> </li> <li id="GUID-ED77E906-6330-567C-B17D-5D66E0A53521"><p>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>. </p> </li> <li id="GUID-1B3F15B1-4DC6-5164-A93B-2F33F1D60064"><p>The TFX render stage calls <xref href="GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704.dita#GUID-51B49D4D-A421-3AE9-A7D6-F4B89CEE0704/GUID-251E3B0E-DA5A-32FC-9253-B4960C8C8A6D"><apiname>MWsScreenRedraw::ScheduleRender()</apiname></xref>, to ensure that it is called again after a short interval. </p> </li> <li id="GUID-F091535F-208E-57B3-9787-593B7C21039B"><p>The client application signals the end of the entry transition and the Window Server scheduler fires. </p> </li> <li id="GUID-B1A48A62-9527-5653-8C20-02E35CF83966"><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> and <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> on the TFX render stage, but without any drawing, giving it the opportunity to run. </p> </li> <li id="GUID-FC40FDEA-F232-5FE9-97F4-37E82B9ACAD9"><p>Over a series of frames, the TFX render stage modifies the element metadata to make the TFX surface (containing view A) slide off, and the UI surface (containing view B) slide on. It does this by updating the elements using <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> calls. </p> </li> <li id="GUID-4A2F9221-FA8B-5943-946A-4633D6124501"><p>When the transition is finished, the TFX render stage removes the TFX surface from composition scene, by calling <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita#GUID-43972649-4BDE-3D93-8658-35F224915A43/GUID-F6AE7CF1-0B56-3243-9E45-1C7A9E49DB83"><apiname>MWsScene::RemoveSceneElement()</apiname></xref>. </p> </li> </ol> </section> </conbody><related-links><link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext> </link> </related-links></concept>
\ No newline at end of file