OpenWF +Support Component Overview

Purpose

The OpenWF Support component has two main +roles:

It provides an implementation +of OpenWF-C native stream.

OpenWF-C represents external +content as native stream sources and targets. Within OpenWF-C, native +streams are an adaptation feature. The OpenWF-C native stream is based on +an opaque handle (WFCNativeStreamType) 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.

The Symbian Surface +Manager and Surface +Update Server components represent external content as composition +surfaces, which are identified by the surface ID (TSurfaceId). +The Symbian OpenWF Support component provides an implementation of native +stream, called SymbianStream, in terms of composition surfaces.

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, typedef SymbianStreamType.

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.

Calling threads must have +the Cleanup Stack enabled.
It repackages the +Surface Update Server API for use by OpenWF-C implementations.

The +OpenWF Support component interfaces with the Surface Update Server using a +C++ update proxy class that implements the MCompositionSurfaceUpdate interface, +which is specified by the Surface Update Server component.

The native +stream implementation supports the Surface Update Server API and re-packages +it for use by OpenWF-C engines.

Registration with the Surface Update +Server is initiated by the OpenWF Support C API method SymbianStreamRegisterScreenNotifications(), +which calls MSurfaceUpdateServerProvider::Register().

Architectural relationships

The following diagram +provides a simplified view of key relationships between the OpenWF Support +component and other key graphics components.

+ Key OpenWF-C Support component relationships + + +

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.

The client application +calls RSurfaceManager::CreateSurface() to create the surface +to render into.
The client application +calls RWindowBase::SetBackgroundSurface() to attach the +surface to a window.
The render stage casts +the address of the TSurfaceId object to the OpenWF-C native +stream (WFCNativeStreamType).
The render stage calls +the OpenWF-C wfcCreateSourceFromStream() function to create +a source from the native stream.
The OpenWF-C engine +creates an EGL sync object.
The client application +renders content to the surface and calls RSurfaceUpdateSession::SubmitUpdate().
The Surface Update Server +calls MCompositionSurfaceUpdate::ContentUpdated() on the +proxy class. This signals the native stream that the content has been updated.
The OpenWF-C Support +component signals the EGL sync object.
The OpenWF-C engine +acquires the buffer and composes its content and then releases the buffer.
The OpenWF-C Support +component composes notifications that ultimately inform the client that the +buffer is ready to render into again.