<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-AFD7E241-7DC5-5C7B-A7FB-D0B6DCF95ECD" xml:lang="en"><title>Rendering

Video to a Graphics Surface Tutorial</title><shortdesc>This tutorial shows you how to use the Video Renderer utility class

to create a new surface for rendering and render a video buffer onto the display. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq id="GUID-438441C2-6B59-566F-91CD-8082A75A831B"><p>Before you start,

you must: </p> <ul>

<li id="GUID-834E7619-14ED-5C02-B9C7-B71D4FAA8EE3"><p>Understand the <xref href="GUID-D1F29744-EB92-5811-A735-B0BC1B352ED5.dita">Video Renderer</xref>. </p> </li>

</ul> </prereq>

<context id="GUID-C2896E81-541E-57A2-92F7-4693975F28C1"><p>You use the <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita"><apiname>CVideoRenderer</apiname></xref> utility

class to render video to a graphics surface. <codeph>CVideoRenderer</codeph> has

two modes: </p> <ul>

<li id="GUID-BAC03F4E-200E-5959-8EE7-40459CC3B302"><p> <b>Timed</b>  </p> <p>In

timed mode, a frame is rendered at a specific time called its presentation

time. A frame's presentation time is the system clock time when that frame

must be visible on the display. <codeph>CVideoRenderer</codeph> launches its

own high-priority thread to handle timed rendering. </p> </li>

<li id="GUID-39DD6061-2847-53F8-A066-9720913F576C"><p> <b>Non-timed</b>  </p> <p>In

non-timed mode, a frame is rendered as soon as possible. Non-timed mode requires

a <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref> to be present in the calling thread. </p> </li>

</ul> <p> <codeph>CVideoRenderer</codeph> uses the <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita"><apiname>MVideoRendererObserver</apiname></xref> interface

to provide notifications about the status of video buffers. <codeph>MVideoRendererObserver</codeph> provides

the following notifications: </p> <table id="GUID-F871259A-07DE-5C4E-8441-7AAF5988E935">

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

<thead>

<row>

<entry> Callback </entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita#GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0/GUID-BCFD3522-F252-3347-AF99-38B1CC7C8722"><apiname>MVideoRendererObserver::MvroBufferDisplayed(TInt,const

                  TTime &amp;)</apiname></xref>  </p> </entry>

<entry><p>A buffer has been rendered onto the display. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita#GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0/GUID-561CE3AE-B3B3-37DF-8836-8636B53E3D76"><apiname>MVideoRendererObserver::MvroBufferSkipped(TInt)</apiname></xref> </p> </entry>

<entry><p>A buffer was skipped in the rendering process. This could be because

it missed its presentation time or an error occurred. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita#GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0/GUID-8C80E5DC-9BCD-3A4E-BC3E-191213BC966A"><apiname>MVideoRendererObserver::MvroVideoBufferAvailable()</apiname></xref> </p> </entry>

<entry><p>A new buffer is available which can be used to store a video frame

for rendering. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p> <b>Note</b>: You must implement <codeph>MVideoRendererObserver</codeph> to

receive these notifications. </p> </context>

<steps id="GUID-6C9FF04E-B88A-57EA-BE76-37D0E08A496F">

<step id="GUID-BB5997B5-8A52-590E-8DE3-73061508883B"><cmd>Create a new Video

Renderer instance by calling <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita#GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6/GUID-2B582029-8A47-316B-A85F-03EEA0B9BB9C"><apiname>CVideoRenderer::NewL(MVideoRendererObserver&amp;,

TBool)</apiname></xref>. </cmd>

<info>Set the <codeph>aTimed</codeph> parameter to <codeph>ETrue</codeph> for

timed mode or <codeph>EFalse</codeph> for non-timed mode. </info>

<stepxmp><codeblock id="GUID-8F673E2F-35B0-50BA-9D01-D65DD496A222" xml:space="preserve">//Create new timed Video Renderer

CVideoRenderer* renderer = CVideoRenderer::NewL(observer, ETrue);</codeblock> </stepxmp>

<stepresult>If in timed mode, <codeph>CVideoRenderer</codeph> launches its

own high-priority thread. </stepresult>

</step>

<step id="GUID-655E965E-0EC8-522E-84E1-1BE770D40CD4"><cmd>Get the list of

supported surface formats by calling <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita#GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6/GUID-14039C33-2A8E-3573-B8E8-0F872A9990D6"><apiname>CVideoRenderer::GetSupportedFormatsL(RArray&lt;TUncompressedVideoFormat&gt;&amp;)</apiname></xref>. </cmd>

<info>The Video Renderer maintains a list of supported formats in an RSS file.

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

Renderer Resource File</xref>. </info>

<stepxmp><codeblock id="GUID-DD5B2FC8-F437-5980-A3FC-8066ED6E624D" xml:space="preserve">//Get an array of supported formats

renderer-&gt;GetSupportedFormatsL(array);</codeblock> </stepxmp>

<info> <codeph>GetSupportedFormatsL()</codeph> returns an array of supported

formats. Use the supported format you require as an input parameter when creating

your surface. </info>

</step>

<step id="GUID-5DF2626B-59D1-505E-9C27-7E88C3D9F5C6"><cmd>Create a new surface

for rendering by calling <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita#GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6/GUID-2E3C8649-B979-3D0C-9580-09EA30BDB883"><apiname>CVideoRenderer::CreateSurfaceL(const

TSize&amp;, TInt, const                 TUncompressedVideoFormat&amp;, TSurfaceId&amp;)</apiname></xref> </cmd>

<stepxmp><codeblock id="GUID-D8CBC1CB-3ED4-5252-9E8E-B475F62891CA" xml:space="preserve">TSurfaceId surfaceId;

renderer-&gt;CreateSurfaceL(size, buffers, format, surfaceId);</codeblock> </stepxmp>

<stepresult> <codeph>CVideoRenderer::CreateSurfaceL()</codeph> returns a Surface

ID for the new surface. You use the Surface ID whenever you need to refer

to the surface, for example, when you need to destroy it. </stepresult>

</step>

<step id="GUID-37C2073C-D6C5-5499-A069-2B74152147AC"><cmd>Retrieve the next

free buffer from the Video Renderer by calling <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita#GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6/GUID-8A620888-269F-3ED8-A71C-C4CED54CFE5D"><apiname>CVideoRenderer::NextBuffer()</apiname></xref>. </cmd>

<stepxmp><codeblock id="GUID-FF65F277-7D82-5ACB-8A10-31AE27831A51" xml:space="preserve">TVideoFrameBuffer* buffer = renderer-&gt;NextBuffer();

// use buffer</codeblock> </stepxmp>

<info><p>Note you should only perform this step after your observer's <codeph>MvroVideoBufferAvailable()</codeph> routine

has been called.</p></info>

<stepresult> <codeph>CVideoRenderer::NextBuffer()</codeph> returns the next

available buffer. </stepresult>

</step>

<step id="GUID-49DD97C3-9989-59F8-B07C-5EDF9302DBFD"><cmd>Render the buffer

onto the display by calling <xref href="GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6.dita#GUID-AFEC8287-41C9-36BB-B0F7-ECC034D34DC6/GUID-01F200BC-C024-396D-BC61-8305938117C9"><apiname>CVideoRenderer::UpdateBuffer(TVideoFrameBuffer

*,const TTime                 &amp;)</apiname></xref>. </cmd>

<info>If you created your Video Renderer in timed mode, set <codeph>aPresentationTime</codeph> to

be the required presentation time for the buffer. If you created your Video

Renderer in non-timed mode, then <codeph>aPresentationTime</codeph> is ignored

and the buffer is displayed as soon as possible. </info>

<stepxmp><codeblock id="GUID-53911688-D44F-5A54-B42E-46CA0F0CE4C8" xml:space="preserve">FillWithData(buffer-&gt;Buffer()); // Fills buffer with data

renderer-&gt;UpdateBuffer(buffer, presentationTime);</codeblock> </stepxmp>

<stepresult>When the buffer has been displayed, you are notified via the <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita#GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0/GUID-BCFD3522-F252-3347-AF99-38B1CC7C8722"><apiname>MVideoRendererObserver::MvroBufferDisplayed(TInt,const TTime   

             &amp;)</apiname></xref> callback. </stepresult>

</step>

</steps>

<result id="GUID-D23C8609-FEDE-55C9-9B61-B680D062F7AF"><p>You have now created

a surface and rendered a video buffer onto the display. </p> </result>

</taskbody><related-links>

<link href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita"><linktext>Video Player

2 Tutorial</linktext></link>

<link href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita"><linktext>Writing a

Controller Plug-in</linktext></link>