<?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-3B9AC7E9-3133-505F-9C1E-EB4BB4969838" xml:lang="en"><title>OpenWF
Composition Interface Overview</title><shortdesc>The OpenWF Composition Interface Component provides the Symbian
platform with a consistent interface to the open-source, cross-platform OpenWF
Composition (OpenWF-C) APIs defined by the Khronos Group. The OpenWF-C Interface
component includes the Khronos-released header files and some Symbian-specific
files. It does not provide any implementations of the APIs. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p><b>Target audience</b>: Device creators. </p>
<section><title>Introduction to OpenWF-C on Symbian</title> <p>OpenWF-C provides
a hardware abstraction layer that allows power-efficient hardware-accelerated
composition on a wide variety of hardware platforms including blitter (memory-memory)
and overlay (memory-less) hardware. OpenWF-C is particularly aimed at systems
with limited memory bandwidth, such as mobile devices. OpenWF-C enables the
UI and the window system stack to be independent of the hardware used to achieve
the composition. </p> <p>OpenWF-C uses a number of opaque handle types (<codeph>WFCHandle</codeph>)
to represent the following key concepts: </p> <ul>
<li id="GUID-4535322F-317D-5612-9B43-41CADD240F2C"><p> <b>Device</b>. An abstract
device that is capable of performing composition operations. Typically this
corresponds to a unit of graphics hardware. All composition operations and
resources are associated with a device. The <codeph>WFCDevice</codeph> subtype
represents an opaque handle to a device. </p> </li>
<li id="GUID-F64F713D-E759-52EE-B8BF-FCACC21C5664"><p> <b>Context</b>. A visual
description of a scene that is applied to a specific target. The context represents
the state required for the composition of the scene. A context can be on-screen
or off-screen but only one on-screen context per screen can render. The <codeph>WFCContext</codeph> subtype
represents an opaque handle to a composition context. </p> </li>
<li id="GUID-B5944275-D933-574F-AC47-17BBAF24AE02"><p> <b>Element</b>. Represents
the positioning and other attributes of content within the composition context.
An element is sometimes referred to as a <b>layer</b>. The <codeph>WFCElement</codeph> subtype
represents an opaque handle to an element. </p> </li>
<li id="GUID-88BA0350-A584-5C2D-BC0D-D406E06772E3"><p> <b>Source</b>. Supplies
the image data that an element can reference as the primary source of its
color data. A source is created from a stream. The <codeph>WFCSource</codeph> subtype
represents an opaque handle to a source. </p> </li>
<li id="GUID-379BCC9D-1471-5CEE-9C90-484A680BF8E5"><p> <b>Stream</b>. A container
for multiple image buffers that share the same properties. Streams encapsulate
the queuing state of the internal buffers. Streams are used for both input
and output pixel data and can be connected to multiple contexts simultaneously.
Ultimately renderers use streams to pass image data to the composition engine.
The stream format is defined as platform-specific. Streams are therefore sometimes
referred to as <b>native streams</b>. The <codeph>WFCNativeStreamType</codeph> subtype
represents the opaque handle to a stream. </p> </li>
</ul> <p> <i>Note</i>: The OpenWF-C APIs are system-level APIs and are not
intended for use by application developers. </p> </section>
<section><title>Architectural relationships</title> <p>The following diagram
shows the key OpenWF-C architectural component relationships within the Symbian
platform. </p> <fig id="GUID-84049713-A7F7-5909-8D26-EC93F53EBFDD">
<title>              OpenWF-C and related Symbian platform components    
       </title>
<image href="GUID-86A6FAC5-FF3C-5C35-A521-5C4BD3823629_d0e281773_href.png" placement="inline"/>
</fig> <ul>
<li id="GUID-03E19B9B-3CE8-5781-B94B-F68CC4D0F207"><p><xref href="GUID-0C4B86B5-530A-5839-86C1-46E7ABE281E0.dita">Window
Server</xref>. The Symbian window management and rendering component. </p> </li>
<li id="GUID-95C24C7C-3FC7-5478-8F90-E3FC668BE0EA"><p><xref href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita">Render
Stages</xref>. An abstraction layer below the Window Server. </p> </li>
<li id="GUID-9859E947-820A-5085-964B-7C803C5CBFD7"><p><xref href="GUID-8BEE0411-C6E9-5840-BE22-EC271A4D97DD.dita">OpenWF-C
Engine</xref>. The implementation of the OpenWF-C interface. </p> </li>
<li id="GUID-D205AFD5-F1CD-558A-9C1B-DA189B8B52EF"><p><xref href="GUID-83510B5B-9725-5272-BF51-23A089178DAC.dita"> OpenWF-C
Support</xref>. Abstracts communication between the OpenWF-C engine and the
Surface Manager, Surface Update Server and the render stage framework and
provides a reference implementation of native stream in terms of Symbian <xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">composition surfaces</xref>. </p> </li>
<li id="GUID-834FF701-708C-5AB0-9DC4-C993CF13444D"><p><xref href="GUID-C7B420DE-CEDA-5D3F-8095-71136E862CDF.dita">Surface
Manager</xref>. Allocates and manages the lifetime and use of composition
surfaces in system memory. Composition surfaces are identified by a 128-bit
identifier (<xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref>). </p> </li>
<li id="GUID-9883ECD8-4739-5461-8425-1B0FAF964F1F"><p><xref href="GUID-81A0A2E9-4BB9-58BF-B2D3-08098E7E9C7C.dita"> Surface
Update Server</xref>. Provides a communication mechanism between the composition
engine and its clients. </p> </li>
<li id="GUID-CDE09188-A96F-5323-982E-D4FBC50C46D7"><p><xref href="GUID-4C166A49-31F7-5315-B797-F97DB52600BC.dita">Display
Driver</xref>. Low-level abstraction of display hardware. </p> </li>
<li id="GUID-5A97D934-DFDC-5398-8C72-049729DFBB62"><p><xref href="GUID-8C6D4350-A38D-57A1-8C8D-C777EA7E8A3E.dita">EGL</xref> (not
shown on diagram). The OpenWF-C engine and support components use EGL sync
objects for synchronization. In addition OpenWF-C clients obtain any extension
functions that the engine implements by using the EGL function, <codeph>eglGetProcAddress()</codeph>. </p> </li>
</ul> </section>
<section><title>Description</title> <p>OpenWF-C is a standard defined by the
Khronos Group (<xref href="http://www.khronos.org/" scope="external">www.khronos.org</xref>)
which defines a C API. The following table provides a link to the relevant
specification.</p> <table id="GUID-A97C8B2F-458A-5A45-88C7-7C997483845D">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>API</entry>
<entry>Specification</entry>
</row>
</thead>
<tbody>
<row>
<entry>OpenWF-C 1.0  </entry>
<entry> <xref href="http://www.khronos.org/registry/wf/specs/OpenWF_Composition_1_0_Specification.pdf" scope="external">http://www.khronos.org/registry/wf/specs/OpenWF_Composition_1_0_Specification.pdf</xref></entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section><title>Header files</title> <p>The OpenWF-C Interface component includes
the Khronos-released header files shown in the following table. Use of these
standard header files helps to ensure binary compatibility for applications
across different Symbian platforms. It also provides source compatibility
between different operating systems. </p> <table id="GUID-9515BFDD-3815-561B-9587-30BB9BBEA802">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Filename</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><filepath>wfc.h</filepath>  </entry>
<entry>Type definitions and function prototypes. </entry>
</row>
<row>
<entry><filepath>wfcext.h</filepath> </entry>
<entry>Defines additional values, functions and data types that may be available
on a platform.  </entry>
</row>
<row>
<entry><filepath>wfcplatform.h</filepath> </entry>
<entry>Platform-specific elements of the specification.  </entry>
</row>
<row>
<entry><filepath>openwfcuids.hrh</filepath> </entry>
<entry>Symbian-defined constants for representing UIDs in MMP files and elsewhere.
 </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section><title>Library file</title> <p>The OpenWF-C Interface component generates
a LIB file called <filepath>libWFC.lib</filepath>. </p></section>
<section> <title>DEF files</title> <p>The following definition (DEF) files
are delivered by the OpenWF-C Interface component in order to ensure binary
compatibility. </p> <table id="GUID-D0B2F40E-FEB3-50EF-81E1-222B80EF9436">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Platform</entry>
<entry>DEF file </entry>
</row>
</thead>
<tbody>
<row>
<entry>ARM </entry>
<entry><filepath> /epoc32/include/platform/def/eabi/libWFCu.def</filepath>  </entry>
</row>
<row>
<entry>WINSCW </entry>
<entry><filepath> /epoc32/include/platform/def/win32/libWFCu.def</filepath> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
</conbody><related-links>
<link href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita"><linktext>OpenWF Composition</linktext>
</link>
<link href="http://www.khronos.org/openwf/" scope="external"><linktext>Khronos
OpenWF Website</linktext></link>
<link href="http://www.khronos.org/developers/library/overview/openwf_overview.pdf" scope="external"><linktext>Khronos OpenWF White Paper</linktext></link>
</related-links></concept>