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-3B9AC7E9-3133-505F-9C1E-EB4BB4969838" xml:lang="en"><title>OpenWF

    13 Composition Interface Overview</title><shortdesc>The OpenWF Composition Interface Component provides the Symbian

    14 platform with a consistent interface to the open-source, cross-platform OpenWF

    15 Composition (OpenWF-C) APIs defined by the Khronos Group. The OpenWF-C Interface

    16 component includes the Khronos-released header files and some Symbian-specific

    17 files. It does not provide any implementations of the APIs. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    18 <p><b>Target audience</b>: Device creators. </p>

    19 <section><title>Introduction to OpenWF-C on Symbian</title> <p>OpenWF-C provides

    20 a hardware abstraction layer that allows power-efficient hardware-accelerated

    21 composition on a wide variety of hardware platforms including blitter (memory-memory)

    22 and overlay (memory-less) hardware. OpenWF-C is particularly aimed at systems

    23 with limited memory bandwidth, such as mobile devices. OpenWF-C enables the

    24 UI and the window system stack to be independent of the hardware used to achieve

    25 the composition. </p> <p>OpenWF-C uses a number of opaque handle types (<codeph>WFCHandle</codeph>)

    26 to represent the following key concepts: </p> <ul>

    27 <li id="GUID-4535322F-317D-5612-9B43-41CADD240F2C"><p> <b>Device</b>. An abstract

    28 device that is capable of performing composition operations. Typically this

    29 corresponds to a unit of graphics hardware. All composition operations and

    30 resources are associated with a device. The <codeph>WFCDevice</codeph> subtype

    31 represents an opaque handle to a device. </p> </li>

    32 <li id="GUID-F64F713D-E759-52EE-B8BF-FCACC21C5664"><p> <b>Context</b>. A visual

    33 description of a scene that is applied to a specific target. The context represents

    34 the state required for the composition of the scene. A context can be on-screen

    35 or off-screen but only one on-screen context per screen can render. The <codeph>WFCContext</codeph> subtype

    36 represents an opaque handle to a composition context. </p> </li>

    37 <li id="GUID-B5944275-D933-574F-AC47-17BBAF24AE02"><p> <b>Element</b>. Represents

    38 the positioning and other attributes of content within the composition context.

    39 An element is sometimes referred to as a <b>layer</b>. The <codeph>WFCElement</codeph> subtype

    40 represents an opaque handle to an element. </p> </li>

    41 <li id="GUID-88BA0350-A584-5C2D-BC0D-D406E06772E3"><p> <b>Source</b>. Supplies

    42 the image data that an element can reference as the primary source of its

    43 color data. A source is created from a stream. The <codeph>WFCSource</codeph> subtype

    44 represents an opaque handle to a source. </p> </li>

    45 <li id="GUID-379BCC9D-1471-5CEE-9C90-484A680BF8E5"><p> <b>Stream</b>. A container

    46 for multiple image buffers that share the same properties. Streams encapsulate

    47 the queuing state of the internal buffers. Streams are used for both input

    48 and output pixel data and can be connected to multiple contexts simultaneously.

    49 Ultimately renderers use streams to pass image data to the composition engine.

    50 The stream format is defined as platform-specific. Streams are therefore sometimes

    51 referred to as <b>native streams</b>. The <codeph>WFCNativeStreamType</codeph> subtype

    52 represents the opaque handle to a stream. </p> </li>

    53 </ul> <p> <i>Note</i>: The OpenWF-C APIs are system-level APIs and are not

    54 intended for use by application developers. </p> </section>

    55 <section><title>Architectural relationships</title> <p>The following diagram

    56 shows the key OpenWF-C architectural component relationships within the Symbian

    57 platform. </p> <fig id="GUID-84049713-A7F7-5909-8D26-EC93F53EBFDD">

    58 <title>              OpenWF-C and related Symbian platform components    

    59        </title>

    60 <image href="GUID-86A6FAC5-FF3C-5C35-A521-5C4BD3823629_d0e250728_href.png" placement="inline"/>

    61 </fig> <ul>

    62 <li id="GUID-03E19B9B-3CE8-5781-B94B-F68CC4D0F207"><p><xref href="GUID-0C4B86B5-530A-5839-86C1-46E7ABE281E0.dita">Window

    63 Server</xref>. The Symbian window management and rendering component. </p> </li>

    64 <li id="GUID-95C24C7C-3FC7-5478-8F90-E3FC668BE0EA"><p><xref href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita">Render

    65 Stages</xref>. An abstraction layer below the Window Server. </p> </li>

    66 <li id="GUID-9859E947-820A-5085-964B-7C803C5CBFD7"><p><xref href="GUID-8BEE0411-C6E9-5840-BE22-EC271A4D97DD.dita">OpenWF-C

    67 Engine</xref>. The implementation of the OpenWF-C interface. </p> </li>

    68 <li id="GUID-D205AFD5-F1CD-558A-9C1B-DA189B8B52EF"><p><xref href="GUID-83510B5B-9725-5272-BF51-23A089178DAC.dita"> OpenWF-C

    69 Support</xref>. Abstracts communication between the OpenWF-C engine and the

    70 Surface Manager, Surface Update Server and the render stage framework and

    71 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>

    72 <li id="GUID-834FF701-708C-5AB0-9DC4-C993CF13444D"><p><xref href="GUID-C7B420DE-CEDA-5D3F-8095-71136E862CDF.dita">Surface

    73 Manager</xref>. Allocates and manages the lifetime and use of composition

    74 surfaces in system memory. Composition surfaces are identified by a 128-bit

    75 identifier (<xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref>). </p> </li>

    76 <li id="GUID-9883ECD8-4739-5461-8425-1B0FAF964F1F"><p><xref href="GUID-81A0A2E9-4BB9-58BF-B2D3-08098E7E9C7C.dita"> Surface

    77 Update Server</xref>. Provides a communication mechanism between the composition

    78 engine and its clients. </p> </li>

    79 <li id="GUID-CDE09188-A96F-5323-982E-D4FBC50C46D7"><p><xref href="GUID-4C166A49-31F7-5315-B797-F97DB52600BC.dita">Display

    80 Driver</xref>. Low-level abstraction of display hardware. </p> </li>

    81 <li id="GUID-5A97D934-DFDC-5398-8C72-049729DFBB62"><p><xref href="GUID-8C6D4350-A38D-57A1-8C8D-C777EA7E8A3E.dita">EGL</xref> (not

    82 shown on diagram). The OpenWF-C engine and support components use EGL sync

    83 objects for synchronization. In addition OpenWF-C clients obtain any extension

    84 functions that the engine implements by using the EGL function, <codeph>eglGetProcAddress()</codeph>. </p> </li>

    85 </ul> </section>

    86 <section><title>Description</title> <p>OpenWF-C is a standard defined by the

    87 Khronos Group (<xref href="http://www.khronos.org/" scope="external">www.khronos.org</xref>)

    88 which defines a C API. The following table provides a link to the relevant

    89 specification.</p> <table id="GUID-A97C8B2F-458A-5A45-88C7-7C997483845D">

    90 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

    91 <thead>

    92 <row>

    93 <entry>API</entry>

    94 <entry>Specification</entry>

    95 </row>

    96 </thead>

    97 <tbody>

    98 <row>

    99 <entry>OpenWF-C 1.0  </entry>

   100 <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>

   101 </row>

   102 </tbody>

   103 </tgroup>

   104 </table> </section>

   105 <section><title>Header files</title> <p>The OpenWF-C Interface component includes

   106 the Khronos-released header files shown in the following table. Use of these

   107 standard header files helps to ensure binary compatibility for applications

   108 across different Symbian platforms. It also provides source compatibility

   109 between different operating systems. </p> <table id="GUID-9515BFDD-3815-561B-9587-30BB9BBEA802">

   110 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

   111 <thead>

   112 <row>

   113 <entry>Filename</entry>

   114 <entry>Description</entry>

   115 </row>

   116 </thead>

   117 <tbody>

   118 <row>

   119 <entry><filepath>wfc.h</filepath>  </entry>

   120 <entry>Type definitions and function prototypes. </entry>

   121 </row>

   122 <row>

   123 <entry><filepath>wfcext.h</filepath> </entry>

   124 <entry>Defines additional values, functions and data types that may be available

   125 on a platform.  </entry>

   126 </row>

   127 <row>

   128 <entry><filepath>wfcplatform.h</filepath> </entry>

   129 <entry>Platform-specific elements of the specification.  </entry>

   130 </row>

   131 <row>

   132 <entry><filepath>openwfcuids.hrh</filepath> </entry>

   133 <entry>Symbian-defined constants for representing UIDs in MMP files and elsewhere.

   134  </entry>

   135 </row>

   136 </tbody>

   137 </tgroup>

   138 </table> </section>

   139 <section><title>Library file</title> <p>The OpenWF-C Interface component generates

   140 a LIB file called <filepath>libWFC.lib</filepath>. </p></section>

   141 <section> <title>DEF files</title> <p>The following definition (DEF) files

   142 are delivered by the OpenWF-C Interface component in order to ensure binary

   143 compatibility. </p> <table id="GUID-D0B2F40E-FEB3-50EF-81E1-222B80EF9436">

   144 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

   145 <thead>

   146 <row>

   147 <entry>Platform</entry>

   148 <entry>DEF file </entry>

   149 </row>

   150 </thead>

   151 <tbody>

   152 <row>

   153 <entry>ARM </entry>

   154 <entry><filepath> /epoc32/include/platform/def/eabi/libWFCu.def</filepath>  </entry>

   155 </row>

   156 <row>

   157 <entry>WINSCW </entry>

   158 <entry><filepath> /epoc32/include/platform/def/win32/libWFCu.def</filepath> </entry>

   159 </row>

   160 </tbody>

   161 </tgroup>

   162 </table> </section>

   163 </conbody><related-links>

   164 <link href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita"><linktext>OpenWF Composition</linktext>

   165 </link>

   166 <link href="http://www.khronos.org/openwf/" scope="external"><linktext>Khronos

   167 OpenWF Website</linktext></link>

   168 <link href="http://www.khronos.org/developers/library/overview/openwf_overview.pdf" scope="external"><linktext>Khronos OpenWF White Paper</linktext></link>

   169 </related-links></concept>