<?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-83510B5B-9725-5272-BF51-23A089178DAC" xml:lang="en"><title>OpenWF
Support Component Overview</title><shortdesc>The OpenWF Support component provides a Symbian-specific implementation
of platform-specific elements of the OpenWF-C specification and abstracts
communication between the OpenWF-C Engine and other Symbian graphics components. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p><b>Target audience</b>: Device creators. </p>
<section><title>Purpose</title> <p>The OpenWF Support component has two main
roles: </p> <ul>
<li id="GUID-EC6A4858-054F-5BFD-9578-D978F85F3EFC"><p> <b>It provides an implementation
of OpenWF-C native stream</b>.  </p> <p>OpenWF-C represents external
content as <b>native stream</b> sources and targets. Within OpenWF-C, native
streams are an adaptation feature. The OpenWF-C native stream is based on
an opaque handle (<xref href="GUID-DF6DF530-EC4E-32D4-9CC8-536F3F2BE83E.dita"><apiname>WFCNativeStreamType</apiname></xref>) and an API consisting
of a number of methods and properties on that handle. This allows the internal
details of content presented to OpenWF-C for composition to be mapped to the
operating environment. </p> <p>The Symbian <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface
Manager</xref> and <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface
Update Server</xref> components represent external content as <xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">composition
surfaces</xref>, which are identified by the surface ID (<xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref>).
The Symbian OpenWF Support component provides an implementation of native
stream, called <xref href="GUID-A99521F3-CA4E-3ED6-9824-3FC40274FC95.dita"><apiname>SymbianStream</apiname></xref>, in terms of composition surfaces. </p> <p>The
Symbian stream API is based on exported C functions in order to simplify integration
with OpenWF-C implementations. Most of the functions create, or take as a
parameter, a handle to a native stream, <codeph>typedef                 SymbianStreamType</codeph>. </p> <p>The
API is intended to operate in the caller’s thread, but is multi-threading-safe.
However, many of the operations perform memory allocation and therefore require
that the client threads present a consistent default heap. This restriction
has performance benefits and does not add an overhead to production use-cases.
However, it complicates test scenarios. </p> <p>Calling threads must have
the Cleanup Stack enabled. </p> </li>
<li id="GUID-9F54BE47-7117-5E41-BA10-52AA9A41D29F"><p> <b>It repackages the
Surface Update Server API for use by OpenWF-C implementations</b>.  </p> <p>The
OpenWF Support component interfaces with the Surface Update Server using a
C++ update proxy class that implements the <xref href="GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD.dita"><apiname>MCompositionSurfaceUpdate</apiname></xref> interface,
which is specified by the Surface Update Server component. </p> <p>The native
stream implementation supports the Surface Update Server API and re-packages
it for use by OpenWF-C engines. </p> <p>Registration with the Surface Update
Server is initiated by the OpenWF Support C API method <xref href="GUID-29F53A6A-531D-32A8-8983-BAF2A772BBA6.dita"><apiname>SymbianStreamRegisterScreenNotifications()</apiname></xref>,
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>
</ul> </section>
<section><title>Architectural relationships</title> <p>The following diagram
provides a simplified view of key relationships between the OpenWF Support
component and other key graphics components. </p> <fig id="GUID-279EBD78-304F-5B1B-8F14-655193CAAC55">
<title>              Key OpenWF-C Support component relationships        
   </title>
<image href="GUID-077B0CE8-FDC1-5BE9-B356-F8E545A0A53D_d0e279068_href.png" placement="inline"/>
</fig> <p>The numbers in the diagram show the approximate sequence when a
rendering client creates a surface and renders into it. This assumes that
the OpenWF-C context has registered the screen with the Surface Update Server
during construction. </p> <ol id="GUID-8EEFF849-DDA2-57C6-8CC3-8CE72A486619">
<li id="GUID-62194273-69CC-5B78-82B2-CF08B9B1C6AE"><p>The client application
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
to render into. </p></li>
<li id="GUID-05D88651-5246-561A-903C-9FC783E3FD6A"><p>The client application
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
surface to a window.</p> </li>
<li id="GUID-98561E7C-580C-5EDA-BFD3-CA753DC9FF81"><p>The render stage casts
the address of the <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref> object to the OpenWF-C native
stream (<xref href="GUID-DF6DF530-EC4E-32D4-9CC8-536F3F2BE83E.dita"><apiname>WFCNativeStreamType</apiname></xref>). </p></li>
<li id="GUID-654428EA-EDDE-5F3A-944D-0B9D7DEE9F69"><p>The render stage calls
the OpenWF-C <xref href="GUID-CFA99080-12D7-32A3-A36C-597EB05F66D1.dita"><apiname>wfcCreateSourceFromStream()</apiname></xref> function to create
a source from the native stream.</p> </li>
<li id="GUID-E3ED12BE-696F-5DC6-B5C6-63D2A4803249"><p>The OpenWF-C engine
creates an EGL sync object. </p></li>
<li id="GUID-FEF314AA-52D1-57CB-B004-C2C46E4A44F2"><p>The client application
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>
<li id="GUID-CD47D078-32B9-5AF0-854D-BAD839BE65E0"><p>The Surface Update Server
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
proxy class. This signals the native stream that the content has been updated. </p></li>
<li id="GUID-EF720A81-8A54-51D1-9061-13CB4EC23B43"><p>The OpenWF-C Support
component signals the EGL sync object. </p></li>
<li id="GUID-18890089-AF4A-553A-AA36-657EB447A006"><p>The OpenWF-C engine
acquires the buffer and composes its content and then releases the buffer. </p></li>
<li id="GUID-59D5475A-CF95-5941-8242-0A44A73DDD7B"><p>The OpenWF-C Support
component composes notifications that ultimately inform the client that the
buffer is ready to render into again.</p> </li>
</ol> </section>
</conbody><related-links>
<link href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita"><linktext>OpenWF Composition</linktext>
</link>
</related-links></concept>