<?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_d0e328424_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>
</related-links></concept>