<?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_d0e251118_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>