Symbian3/PDK/Source/GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita
changeset 5 f345bda72bc4
parent 3 46218c8b8afa
child 14 578be2adaf3e
equal deleted inserted replaced
4:4816d766a08a 5:f345bda72bc4
    15 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
    15 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
    16 audience</b>: Device creators. </p>
    16 audience</b>: Device creators. </p>
    17 <p>The <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages
    17 <p>The <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages
    18 Overview</xref> introduced some of the interfaces that render stages implement.
    18 Overview</xref> introduced some of the interfaces that render stages implement.
    19 Here we will look at those in more detail, along with some of the other interfaces. </p>
    19 Here we will look at those in more detail, along with some of the other interfaces. </p>
    20 <section><title>MWsObjectProvider</title> <p> <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> is
    20 <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
    21 a Window Server plug-in framework interface, which provides a mechanism through
    21 a Window Server plug-in framework interface, which provides a mechanism through
    22 which classes can offer extension interfaces. Render stages and most of the
    22 which classes can offer extension interfaces. Render stages and most of the
    23 related classes implement this interface. </p> </section>
    23 related classes implement this interface. </p> </section>
    24 <section><title>CWsRenderStage</title> <p> <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita"><apiname>CWsRenderStage</apiname></xref> is
    24 <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
    25 an abstract class that all render stages must derive from. It has two pure
    25 an abstract class that all render stages must derive from. It has two pure
    26 virtual functions: <codeph>Begin()</codeph> and <codeph>End()</codeph>, which
    26 virtual functions: <codeph>Begin()</codeph> and <codeph>End()</codeph>, which
    27 must be implemented in the concrete class. </p> <p>The Window Server's output
    27 must be implemented in the concrete class. </p> <p>The Window Server's output
    28 to the render stage pipeline is not a continuous stream, but instead consists
    28 to the render stage pipeline is not a continuous stream, but instead consists
    29 of batches of drawing operations. When client drawing or server-side animations
    29 of batches of drawing operations. When client drawing or server-side animations
    92 does not currently provide extended bitmap functionality in the main render
    92 does not currently provide extended bitmap functionality in the main render
    93 stages, it does provide a test extended bitmap render stage. You can use this
    93 stages, it does provide a test extended bitmap render stage. You can use this
    94 as an example when you implement your own extended bitmap functionality. </p> <p>For
    94 as an example when you implement your own extended bitmap functionality. </p> <p>For
    95 more information, see <xref href="GUID-D76C7759-739D-5C98-B718-7297687FE630.dita">Extended
    95 more information, see <xref href="GUID-D76C7759-739D-5C98-B718-7297687FE630.dita">Extended
    96 Bitmaps</xref>. </p> </section>
    96 Bitmaps</xref>. </p> </section>
    97 <section><title>MWsScene </title> <p> <xref href="GUID-43972649-4BDE-3D93-8658-35F224915A43.dita"><apiname>MWsScene</apiname></xref> is the composition
    97 <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
    98 context interface for use with <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
    98 context interface for use with <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
    99 composition</xref>. It is a mandatory interface. However, like <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref>,
    99 composition</xref>. It is a mandatory interface. However, like <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref>,
   100 some render stages might simply delegate to the next render stage rather than
   100 some render stages might simply delegate to the next render stage rather than
   101 providing their own implementations. The final render stage in the chain typically
   101 providing their own implementations. The final render stage in the chain typically
   102 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
   102 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
   134 Marks the surface as no longer in use beyond its inclusion in the scene. </p> </li>
   134 Marks the surface as no longer in use beyond its inclusion in the scene. </p> </li>
   135 </ul> <p>Any updates to the scene introduced by the render stage (such as
   135 </ul> <p>Any updates to the scene introduced by the render stage (such as
   136 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
   136 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
   137 commit the scene. </p> </section>
   137 commit the scene. </p> </section>
   138 
   138 
   139 <section><title>MWsElement</title> <p> <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> is a
   139 <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
   140 mandatory interface for managing scene elements when <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
   140 mandatory interface for managing scene elements when <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF
   141 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
   141 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
   142 than the object provider mechanism. </p> <p>The <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> interface
   142 than the object provider mechanism. </p> <p>The <xref href="GUID-48B10795-1C8F-3D21-9637-6C7A02C95C75.dita"><apiname>MWsElement</apiname></xref> interface
   143 provides a way of associating metadata with an image source. From the render
   143 provides a way of associating metadata with an image source. From the render
   144 stage's point of view, the image source is a surface that is connected to
   144 stage's point of view, the image source is a surface that is connected to
   167 <li id="GUID-8B50BD6E-5F9A-5690-99CC-73AE8D129B52"><p>Render stage flags—these
   167 <li id="GUID-8B50BD6E-5F9A-5690-99CC-73AE8D129B52"><p>Render stage flags—these
   168 provide information to the render stages, such as whether the UI surface is
   168 provide information to the render stages, such as whether the UI surface is
   169 always on top. </p> </li>
   169 always on top. </p> </li>
   170 </ul> </section>
   170 </ul> </section>
   171 
   171 
   172 <section><title>MWsScreenDevice</title> <p> <xref href="GUID-B1E048A2-D5E8-3E7F-A6AC-6B8F3ED3067C.dita"><apiname>MWsScreenDevice</apiname></xref> is
   172 <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
   173 the interface for managing the screen. It provides functions for controlling
   173 the interface for managing the screen. It provides functions for controlling
   174 rotation and fetching data from the screen such as a screen snapshot. </p> </section>
   174 rotation and fetching data from the screen such as a screen snapshot. </p> </section>
   175 <section><title>MWsTextCursor</title> <p> <xref href="GUID-F43CBB9C-238B-33C5-B872-AAE0104F047E.dita"><apiname>MWsTextCursor</apiname></xref> is
   175 <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
   176 an interface that enables render stages to implement a text cursor to represent
   176 an interface that enables render stages to implement a text cursor to represent
   177 the flashing bar or rectangle that represents the current position when editing
   177 the flashing bar or rectangle that represents the current position when editing
   178 text. </p> <p>Prior to the introduction of ScreenPlay text cursors were drawn
   178 text. </p> <p>Prior to the introduction of ScreenPlay text cursors were drawn
   179 using XOR drawing because it provides high contrast against the background.
   179 using XOR drawing because it provides high contrast against the background.
   180 Render stages can implement this interface using the same approach but it
   180 Render stages can implement this interface using the same approach but it
   184 replace the text cursor with a sprite. This means that user themes can use
   184 replace the text cursor with a sprite. This means that user themes can use
   185 a sprite that matches the text—for example, a white sprite with white text
   185 a sprite that matches the text—for example, a white sprite with white text
   186 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
   186 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
   187 is not used when drawing text cursors for that client. Instead, the text cursor
   187 is not used when drawing text cursors for that client. Instead, the text cursor
   188 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>
   188 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>
   189 <section><title>MWsFader</title> <p> <xref href="GUID-1CF41CFD-27C8-39D7-A615-18CE765436DE.dita"><apiname>MWsFader</apiname></xref> is the interface
   189 <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
   190 for providing fading capabilities. </p> </section>
   190 for providing fading capabilities. </p> </section>
   191 <section><title>MWsWindowTreeObserver</title> <p> <xref href="GUID-028CC583-AC32-3D60-943A-A80F84E05DD2.dita"><apiname>MWsWindowTreeObserver</apiname></xref> is
   191 <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
   192 an optional interface that enables a render stage to create a replica of the
   192 an optional interface that enables a render stage to create a replica of the
   193 window tree, known as the <b>visuals tree</b>. The Window Server uses this
   193 window tree, known as the <b>visuals tree</b>. The Window Server uses this
   194 interface to tell the render stage about the window tree structure and changes
   194 interface to tell the render stage about the window tree structure and changes
   195 to window tree nodes. Note that this interface considers animations and sprites
   195 to window tree nodes. Note that this interface considers animations and sprites
   196 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
   196 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
   235 a window's handle from the <xref href="GUID-7837D4F3-4BF4-344B-B987-6789060553B3.dita"><apiname>MWsWindowTreeNode</apiname></xref> object returned
   235 a window's handle from the <xref href="GUID-7837D4F3-4BF4-344B-B987-6789060553B3.dita"><apiname>MWsWindowTreeNode</apiname></xref> object returned
   236 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>:
   236 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>:
   237 Communication of the window handle from the client to the render stage is
   237 Communication of the window handle from the client to the render stage is
   238 beyond the scope of this documentation. </p> </li>
   238 beyond the scope of this documentation. </p> </li>
   239 </ul> </section>
   239 </ul> </section>
   240 <section><title>MWsWindowVisibilityNotifier</title> <p> <xref href="GUID-FF3EE463-E775-3948-B1EB-66135E24A623.dita"><apiname>MWsWindowVisibilityNotifier</apiname></xref> is
   240 <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
   241 an optional interface that enables a render stage to communicate changes in
   241 an optional interface that enables a render stage to communicate changes in
   242 the visibility of windows and other nodes in the window tree to the Window
   242 the visibility of windows and other nodes in the window tree to the Window
   243 Server. A render stage that works in <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">change-tracking
   243 Server. A render stage that works in <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">change-tracking
   244 rendering mode</xref> must implement this interface. </p> <p>When the Window
   244 rendering mode</xref> must implement this interface. </p> <p>When the Window
   245 Server is in its default dirty-rectangle tracking mode, it tracks which windows
   245 Server is in its default dirty-rectangle tracking mode, it tracks which windows
   253 tracking of visible regions is delegated to the render stage. At the minimum,
   253 tracking of visible regions is delegated to the render stage. At the minimum,
   254 the render stage must set the visible region to be the whole window or none
   254 the render stage must set the visible region to be the whole window or none
   255 of it. </p> <p>The Window Server implements the <xref href="GUID-9CF4DEE1-57D8-3F57-93B2-6EB701262AD7.dita"><apiname>MWsWindowVisibilityObserver</apiname></xref> interface
   255 of it. </p> <p>The Window Server implements the <xref href="GUID-9CF4DEE1-57D8-3F57-93B2-6EB701262AD7.dita"><apiname>MWsWindowVisibilityObserver</apiname></xref> interface
   256 through which it responds to visibility change notifications sent by the render
   256 through which it responds to visibility change notifications sent by the render
   257 stage. </p> </section>
   257 stage. </p> </section>
   258 <section><title>MWsDisplayControl</title> <p> <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> is
   258 <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
   259 the interface for controlling the display configuration. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
   259 the interface for controlling the display configuration. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
   260 Stage Display Control and Mapping</xref> for more information. </p> </section>
   260 Stage Display Control and Mapping</xref> for more information. </p> </section>
   261 <section><title>MWsDisplayMapping</title> <p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> is
   261 <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
   262 the interface for mapping between coordinate spaces. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
   262 the interface for mapping between coordinate spaces. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
   263 Stage Display Control and Mapping</xref> for more information. </p> </section>
   263 Stage Display Control and Mapping</xref> for more information. </p> </section>
   264 <section><title>MWsDisplayPolicy</title> <p> <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is
   264 <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
   265 an optional interface, which if implemented, determines the UI to composition
   265 an optional interface, which if implemented, determines the UI to composition
   266 mapping policy. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
   266 mapping policy. See <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">Render
   267 Stage Display Control and Mapping</xref> for more information. </p> </section>
   267 Stage Display Control and Mapping</xref> for more information. </p> </section>
   268 </conbody><related-links>
   268 </conbody><related-links>
   269 <link href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita"><linktext>Render Stage
   269 <link href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita"><linktext>Render Stage