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