|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-83510B5B-9725-5272-BF51-23A089178DAC" xml:lang="en"><title>OpenWF |
|
13 Support Component Overview</title><shortdesc>The OpenWF Support component provides a Symbian-specific implementation |
|
14 of platform-specific elements of the OpenWF-C specification and abstracts |
|
15 communication between the OpenWF-C Engine and other Symbian graphics components. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p><b>Target audience</b>: Device creators. </p> |
|
17 <section><title>Purpose</title> <p>The OpenWF Support component has two main |
|
18 roles: </p> <ul> |
|
19 <li id="GUID-EC6A4858-054F-5BFD-9578-D978F85F3EFC"><p> <b>It provides an implementation |
|
20 of OpenWF-C native stream</b>. </p> <p>OpenWF-C represents external |
|
21 content as <b>native stream</b> sources and targets. Within OpenWF-C, native |
|
22 streams are an adaptation feature. The OpenWF-C native stream is based on |
|
23 an opaque handle (<xref href="GUID-DF6DF530-EC4E-32D4-9CC8-536F3F2BE83E.dita"><apiname>WFCNativeStreamType</apiname></xref>) and an API consisting |
|
24 of a number of methods and properties on that handle. This allows the internal |
|
25 details of content presented to OpenWF-C for composition to be mapped to the |
|
26 operating environment. </p> <p>The Symbian <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface |
|
27 Manager</xref> and <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface |
|
28 Update Server</xref> components represent external content as <xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">composition |
|
29 surfaces</xref>, which are identified by the surface ID (<xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref>). |
|
30 The Symbian OpenWF Support component provides an implementation of native |
|
31 stream, called <xref href="GUID-A99521F3-CA4E-3ED6-9824-3FC40274FC95.dita"><apiname>SymbianStream</apiname></xref>, in terms of composition surfaces. </p> <p>The |
|
32 Symbian stream API is based on exported C functions in order to simplify integration |
|
33 with OpenWF-C implementations. Most of the functions create, or take as a |
|
34 parameter, a handle to a native stream, <codeph>typedef SymbianStreamType</codeph>. </p> <p>The |
|
35 API is intended to operate in the caller’s thread, but is multi-threading-safe. |
|
36 However, many of the operations perform memory allocation and therefore require |
|
37 that the client threads present a consistent default heap. This restriction |
|
38 has performance benefits and does not add an overhead to production use-cases. |
|
39 However, it complicates test scenarios. </p> <p>Calling threads must have |
|
40 the Cleanup Stack enabled. </p> </li> |
|
41 <li id="GUID-9F54BE47-7117-5E41-BA10-52AA9A41D29F"><p> <b>It repackages the |
|
42 Surface Update Server API for use by OpenWF-C implementations</b>. </p> <p>The |
|
43 OpenWF Support component interfaces with the Surface Update Server using a |
|
44 C++ update proxy class that implements the <xref href="GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD.dita"><apiname>MCompositionSurfaceUpdate</apiname></xref> interface, |
|
45 which is specified by the Surface Update Server component. </p> <p>The native |
|
46 stream implementation supports the Surface Update Server API and re-packages |
|
47 it for use by OpenWF-C engines. </p> <p>Registration with the Surface Update |
|
48 Server is initiated by the OpenWF Support C API method <xref href="GUID-29F53A6A-531D-32A8-8983-BAF2A772BBA6.dita"><apiname>SymbianStreamRegisterScreenNotifications()</apiname></xref>, |
|
49 which calls <xref href="GUID-9EE85F40-6F8D-3A1B-A841-E4B37F7A4C2F.dita#GUID-9EE85F40-6F8D-3A1B-A841-E4B37F7A4C2F/GUID-2C66BB51-08F4-3AE8-8B98-29DC6CFBFD37"><apiname>MSurfaceUpdateServerProvider::Register()</apiname></xref>. </p> </li> |
|
50 </ul> </section> |
|
51 <section><title>Architectural relationships</title> <p>The following diagram |
|
52 provides a simplified view of key relationships between the OpenWF Support |
|
53 component and other key graphics components. </p> <fig id="GUID-279EBD78-304F-5B1B-8F14-655193CAAC55"> |
|
54 <title> Key OpenWF-C Support component relationships |
|
55 </title> |
|
56 <image href="GUID-077B0CE8-FDC1-5BE9-B356-F8E545A0A53D_d0e251118_href.png" placement="inline"/> |
|
57 </fig> <p>The numbers in the diagram show the approximate sequence when a |
|
58 rendering client creates a surface and renders into it. This assumes that |
|
59 the OpenWF-C context has registered the screen with the Surface Update Server |
|
60 during construction. </p> <ol id="GUID-8EEFF849-DDA2-57C6-8CC3-8CE72A486619"> |
|
61 <li id="GUID-62194273-69CC-5B78-82B2-CF08B9B1C6AE"><p>The client application |
|
62 calls <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita#GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9/GUID-2FA29D5C-134B-3635-A208-7187131D72EC"><apiname>RSurfaceManager::CreateSurface()</apiname></xref> to create the surface |
|
63 to render into. </p></li> |
|
64 <li id="GUID-05D88651-5246-561A-903C-9FC783E3FD6A"><p>The client application |
|
65 calls <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-4EBFFA14-418A-3A2A-B147-39BFC96CE45F"><apiname>RWindowBase::SetBackgroundSurface()</apiname></xref> to attach the |
|
66 surface to a window.</p> </li> |
|
67 <li id="GUID-98561E7C-580C-5EDA-BFD3-CA753DC9FF81"><p>The render stage casts |
|
68 the address of the <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref> object to the OpenWF-C native |
|
69 stream (<xref href="GUID-DF6DF530-EC4E-32D4-9CC8-536F3F2BE83E.dita"><apiname>WFCNativeStreamType</apiname></xref>). </p></li> |
|
70 <li id="GUID-654428EA-EDDE-5F3A-944D-0B9D7DEE9F69"><p>The render stage calls |
|
71 the OpenWF-C <xref href="GUID-CFA99080-12D7-32A3-A36C-597EB05F66D1.dita"><apiname>wfcCreateSourceFromStream()</apiname></xref> function to create |
|
72 a source from the native stream.</p> </li> |
|
73 <li id="GUID-E3ED12BE-696F-5DC6-B5C6-63D2A4803249"><p>The OpenWF-C engine |
|
74 creates an EGL sync object. </p></li> |
|
75 <li id="GUID-FEF314AA-52D1-57CB-B004-C2C46E4A44F2"><p>The client application |
|
76 renders content to the surface and calls <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref>. </p></li> |
|
77 <li id="GUID-CD47D078-32B9-5AF0-854D-BAD839BE65E0"><p>The Surface Update Server |
|
78 calls <xref href="GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD.dita#GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD/GUID-64037182-167B-360C-B210-65B0861D4300"><apiname>MCompositionSurfaceUpdate::ContentUpdated()</apiname></xref> on the |
|
79 proxy class. This signals the native stream that the content has been updated. </p></li> |
|
80 <li id="GUID-EF720A81-8A54-51D1-9061-13CB4EC23B43"><p>The OpenWF-C Support |
|
81 component signals the EGL sync object. </p></li> |
|
82 <li id="GUID-18890089-AF4A-553A-AA36-657EB447A006"><p>The OpenWF-C engine |
|
83 acquires the buffer and composes its content and then releases the buffer. </p></li> |
|
84 <li id="GUID-59D5475A-CF95-5941-8242-0A44A73DDD7B"><p>The OpenWF-C Support |
|
85 component composes notifications that ultimately inform the client that the |
|
86 buffer is ready to render into again.</p> </li> |
|
87 </ol> </section> |
|
88 </conbody><related-links> |
|
89 <link href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita"><linktext>OpenWF Composition</linktext> |
|
90 </link> |
|
91 </related-links></concept> |