--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-AFD7E241-7DC5-5C7B-A7FB-D0B6DCF95ECD.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,120 @@
+<?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>
\ No newline at end of file