<?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-D1F29744-EB92-5811-A735-B0BC1B352ED5" xml:lang="en"><title>Video

Renderer Overview</title><shortdesc>This topic describes the Video Renderer component and is aimed

at video controller and video adaptation developers who want to take advantage

of rendering to graphics surfaces. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Purpose</title> <p>The Video Renderer renders video to a graphics

surface. The Video Renderer can be used by video decoders, video post-processors

and video controllers. It can also be used to implement the <xref href="GUID-FC735256-6CB5-5EED-8E7D-42EFA039E6FD.dita">ECam

viewfinder</xref> using a graphics surface. </p> <p>The Video Renderer has

two modes: timed and non-timed. In timed mode, the Video Renderer renders

a frame at a specific time. In non-timed mode, the Video Renderer renders

a frame immediately. </p> <p>On the Symbian platform, <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> (also

known as the New Graphics Architecture or NGA) enables rendering to a graphics

surface. The Video Renderer can only be used in conjunction with ScreenPlay.

The Video Renderer does not contain any video or graphics processing software.

All operations that are needed to display video content on the screen are

handled by the <xref href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita">Graphics

Composition Components</xref>. </p> <p>The Video Renderer component is classified

as Optional Replaceable. This means that device creators can either substitute

it with their own implementation or remove it if they do not want to use it. </p> </section>

<section><title>Required background</title> <p>To understand the Video Renderer,

the reader must be familiar with the following: </p> <ul>

<li id="GUID-EAFD5638-403D-5D2F-A787-BD41EEE13CC3"><p><xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">Graphics

Surfaces</xref>  </p> </li>

</ul> </section>

<section><title>Architecture</title> <p>The Video Renderer can be implemented

in two different ways, as shown in the following diagram: </p> <fig id="GUID-33691E6E-8B90-579B-876B-6F14E953BB7C">

<title>              The two Video Renderer architectures            </title>

<image href="GUID-BE11D652-3B39-51D2-ACE9-571E8EB71E94_d0e321954_href.png" placement="inline"/>

</fig> <p> <b>Note</b>: For simplicity, only the Multimedia Framework client/controller

thread boundary has been shown; other thread boundaries may exist. </p> <p>In

both architectures, the <xref href="GUID-0EE3180B-4814-517E-A6DD-748136C17D55.dita">Video

Client API</xref> (<xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>) is responsible

for retrieving graphics surface handles from the video player controller and

registering them with the <xref href="GUID-0C4B86B5-530A-5839-86C1-46E7ABE281E0.dita">Window

Server</xref>. The difference in the two approaches is in the implementation

of the video adaptation and the video player controller: </p> <ul>

<li id="GUID-F47C767B-5040-5E2D-B4A4-E6635B417371"><p> <b>Video adaptation

approach</b>  </p> <p>The video adaptation uses the Video Renderer to create

and manage graphics surfaces and handle video rendering. The video player

controller simply passes surface information between <xref href="GUID-EB58901D-66BD-56BF-B0CD-5FC4F73F06F3.dita">DevVideoPlay</xref> and

the client. An example of this is the Symbian reference AVI player controller

and <xref href="http://developer.symbian.org/wiki/index.php/File:Xvid.zip" scope="external">XVid decoder</xref>. Symbian recommends this approach for

new implementations. </p> </li>

<li id="GUID-64AFC8B9-9BED-5B6D-8946-89BBBF9ACBC5"><p> <b>Video player controller

approach</b>  </p> <p>The video player controller uses the Video Renderer

to create and manage graphics surfaces, and handle video rendering and timing.

This approach is suitable for implementations where DevVideoPlay is only used

as a codec interface or where DevVideoPlay is not used. </p> </li>

</ul> <p>In both architectures, the <xref href="GUID-81A0A2E9-4BB9-58BF-B2D3-08098E7E9C7C.dita">Surface

Update</xref> component provides a communication channel between the Video

Renderer and the composition engine. </p> </section>

<section><title>APIs</title> <p>The Video Renderer component contains the

following DLL with its associated APIs: </p> <table id="GUID-78EF57A1-34BE-5D0B-9B9B-4328FEC0C2C9">

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

<thead>

<row>

<entry>DLL</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <b>videorenderer.dll </b>  </p> </entry>

<entry><p>The functionality of the Video Renderer is provided by the following

key classes: </p> <ul>

<li id="GUID-D40C598C-FCE4-5840-A58D-A1A8BAB2E52E"><p> <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita"><apiname>CVideoRenderer</apiname></xref> -

a utility class for rendering video to graphics surfaces on behalf of a client. </p> </li>

<li id="GUID-1C64FB8F-DAAD-5C76-9650-2984B68499E5"><p> <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita"><apiname>MVideoRendererObserver</apiname></xref> -

an observer class that provides notifications about the availability and status

of buffers submitted for rendering. </p> </li>

<li id="GUID-DB5CFCD9-7ED3-54F6-8E88-182481933170"><p> <xref href="GUID-95DB347F-D669-394D-9BD4-3A2BD18554D4.dita"><apiname>TVideoFrameBuffer</apiname></xref> -

represents a buffer for a single decoded video picture. </p> </li>

</ul> <p>The Video Renderer also uses a resource file (<filepath>videorenderer.rss</filepath>)

to store supported pixel formats and timed mode values. For more information,

see <xref href="GUID-6021BE18-3416-55DF-A628-0071024D7586.dita">Video Renderer

Resource File</xref>. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Typical uses</title> <p>The Video Renderer is used for the

following: </p> <ul>

<li id="GUID-89CA724E-B873-5C9E-8923-700C48D6EC7A"><p>Creating a surface for

video rendering </p> </li>

<li id="GUID-0698BBA1-E5EB-561A-AA77-27C80927C1DF"><p>Supplying buffers to

decode video frames into </p> </li>

<li id="GUID-F650FB8E-2222-5BAD-B7A3-3F90DDCCD2F7"><p>Rendering a buffer on

the display (timed or non-timed) </p> </li>

<li id="GUID-78941DFB-FBDF-5583-9FCE-DDD53818D202"><p>Destroying a surface. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-0EE3180B-4814-517E-A6DD-748136C17D55.dita"><linktext>Video Client</linktext>

</link>

<link href="GUID-DDE1A8A9-1D67-53BF-8A65-340F139AD4AB.dita"><linktext>Multimedia

Framework (MMF)</linktext></link>

<link href="GUID-97F83011-BE3C-512C-9599-028CBB92BD51.dita"><linktext>Multimedia

Plug-ins</linktext></link>

<link href="GUID-842D8124-554F-5D89-9E20-8B48EA539D2F.dita"><linktext>Video HAI</linktext>

</link>

<link href="GUID-63CB6C7E-44EC-5D0B-A37D-FE78F7D76592.dita"><linktext>Graphics

Surface Composition Collection</linktext></link>

<link href="GUID-C7B420DE-CEDA-5D3F-8095-71136E862CDF.dita"><linktext>Surface Manager

Component</linktext></link>