|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-AFD7E241-7DC5-5C7B-A7FB-D0B6DCF95ECD" xml:lang="en"><title>Rendering |
|
13 Video to a Graphics Surface Tutorial</title><shortdesc>This tutorial shows you how to use the Video Renderer utility class |
|
14 to create a new surface for rendering and render a video buffer onto the display. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
15 <prereq id="GUID-438441C2-6B59-566F-91CD-8082A75A831B"><p>Before you start, |
|
16 you must: </p> <ul> |
|
17 <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> |
|
18 </ul> </prereq> |
|
19 <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 |
|
20 class to render video to a graphics surface. <codeph>CVideoRenderer</codeph> has |
|
21 two modes: </p> <ul> |
|
22 <li id="GUID-BAC03F4E-200E-5959-8EE7-40459CC3B302"><p> <b>Timed</b> </p> <p>In |
|
23 timed mode, a frame is rendered at a specific time called its presentation |
|
24 time. A frame's presentation time is the system clock time when that frame |
|
25 must be visible on the display. <codeph>CVideoRenderer</codeph> launches its |
|
26 own high-priority thread to handle timed rendering. </p> </li> |
|
27 <li id="GUID-39DD6061-2847-53F8-A066-9720913F576C"><p> <b>Non-timed</b> </p> <p>In |
|
28 non-timed mode, a frame is rendered as soon as possible. Non-timed mode requires |
|
29 a <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref> to be present in the calling thread. </p> </li> |
|
30 </ul> <p> <codeph>CVideoRenderer</codeph> uses the <xref href="GUID-6BB74A8C-B243-368C-8114-E9D4C4D511D0.dita"><apiname>MVideoRendererObserver</apiname></xref> interface |
|
31 to provide notifications about the status of video buffers. <codeph>MVideoRendererObserver</codeph> provides |
|
32 the following notifications: </p> <table id="GUID-F871259A-07DE-5C4E-8441-7AAF5988E935"> |
|
33 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
34 <thead> |
|
35 <row> |
|
36 <entry> Callback </entry> |
|
37 <entry>Description</entry> |
|
38 </row> |
|
39 </thead> |
|
40 <tbody> |
|
41 <row> |
|
42 <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 |
|
43 TTime &)</apiname></xref> </p> </entry> |
|
44 <entry><p>A buffer has been rendered onto the display. </p> </entry> |
|
45 </row> |
|
46 <row> |
|
47 <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> |
|
48 <entry><p>A buffer was skipped in the rendering process. This could be because |
|
49 it missed its presentation time or an error occurred. </p> </entry> |
|
50 </row> |
|
51 <row> |
|
52 <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> |
|
53 <entry><p>A new buffer is available which can be used to store a video frame |
|
54 for rendering. </p> </entry> |
|
55 </row> |
|
56 </tbody> |
|
57 </tgroup> |
|
58 </table> <p> <b>Note</b>: You must implement <codeph>MVideoRendererObserver</codeph> to |
|
59 receive these notifications. </p> </context> |
|
60 <steps id="GUID-6C9FF04E-B88A-57EA-BE76-37D0E08A496F"> |
|
61 <step id="GUID-BB5997B5-8A52-590E-8DE3-73061508883B"><cmd>Create a new Video |
|
62 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&, |
|
63 TBool)</apiname></xref>. </cmd> |
|
64 <info>Set the <codeph>aTimed</codeph> parameter to <codeph>ETrue</codeph> for |
|
65 timed mode or <codeph>EFalse</codeph> for non-timed mode. </info> |
|
66 <stepxmp><codeblock id="GUID-8F673E2F-35B0-50BA-9D01-D65DD496A222" xml:space="preserve">//Create new timed Video Renderer |
|
67 CVideoRenderer* renderer = CVideoRenderer::NewL(observer, ETrue);</codeblock> </stepxmp> |
|
68 <stepresult>If in timed mode, <codeph>CVideoRenderer</codeph> launches its |
|
69 own high-priority thread. </stepresult> |
|
70 </step> |
|
71 <step id="GUID-655E965E-0EC8-522E-84E1-1BE770D40CD4"><cmd>Get the list of |
|
72 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<TUncompressedVideoFormat>&)</apiname></xref>. </cmd> |
|
73 <info>The Video Renderer maintains a list of supported formats in an RSS file. |
|
74 For more information, see <xref href="GUID-6021BE18-3416-55DF-A628-0071024D7586.dita">Video |
|
75 Renderer Resource File</xref>. </info> |
|
76 <stepxmp><codeblock id="GUID-DD5B2FC8-F437-5980-A3FC-8066ED6E624D" xml:space="preserve">//Get an array of supported formats |
|
77 renderer->GetSupportedFormatsL(array);</codeblock> </stepxmp> |
|
78 <info> <codeph>GetSupportedFormatsL()</codeph> returns an array of supported |
|
79 formats. Use the supported format you require as an input parameter when creating |
|
80 your surface. </info> |
|
81 </step> |
|
82 <step id="GUID-5DF2626B-59D1-505E-9C27-7E88C3D9F5C6"><cmd>Create a new surface |
|
83 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 |
|
84 TSize&, TInt, const TUncompressedVideoFormat&, TSurfaceId&)</apiname></xref> </cmd> |
|
85 <stepxmp><codeblock id="GUID-D8CBC1CB-3ED4-5252-9E8E-B475F62891CA" xml:space="preserve">TSurfaceId surfaceId; |
|
86 renderer->CreateSurfaceL(size, buffers, format, surfaceId);</codeblock> </stepxmp> |
|
87 <stepresult> <codeph>CVideoRenderer::CreateSurfaceL()</codeph> returns a Surface |
|
88 ID for the new surface. You use the Surface ID whenever you need to refer |
|
89 to the surface, for example, when you need to destroy it. </stepresult> |
|
90 </step> |
|
91 <step id="GUID-37C2073C-D6C5-5499-A069-2B74152147AC"><cmd>Retrieve the next |
|
92 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> |
|
93 <stepxmp><codeblock id="GUID-FF65F277-7D82-5ACB-8A10-31AE27831A51" xml:space="preserve">TVideoFrameBuffer* buffer = renderer->NextBuffer(); |
|
94 // use buffer</codeblock> </stepxmp> |
|
95 <info><p>Note you should only perform this step after your observer's <codeph>MvroVideoBufferAvailable()</codeph> routine |
|
96 has been called.</p></info> |
|
97 <stepresult> <codeph>CVideoRenderer::NextBuffer()</codeph> returns the next |
|
98 available buffer. </stepresult> |
|
99 </step> |
|
100 <step id="GUID-49DD97C3-9989-59F8-B07C-5EDF9302DBFD"><cmd>Render the buffer |
|
101 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 |
|
102 *,const TTime &)</apiname></xref>. </cmd> |
|
103 <info>If you created your Video Renderer in timed mode, set <codeph>aPresentationTime</codeph> to |
|
104 be the required presentation time for the buffer. If you created your Video |
|
105 Renderer in non-timed mode, then <codeph>aPresentationTime</codeph> is ignored |
|
106 and the buffer is displayed as soon as possible. </info> |
|
107 <stepxmp><codeblock id="GUID-53911688-D44F-5A54-B42E-46CA0F0CE4C8" xml:space="preserve">FillWithData(buffer->Buffer()); // Fills buffer with data |
|
108 renderer->UpdateBuffer(buffer, presentationTime);</codeblock> </stepxmp> |
|
109 <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 |
|
110 &)</apiname></xref> callback. </stepresult> |
|
111 </step> |
|
112 </steps> |
|
113 <result id="GUID-D23C8609-FEDE-55C9-9B61-B680D062F7AF"><p>You have now created |
|
114 a surface and rendered a video buffer onto the display. </p> </result> |
|
115 </taskbody><related-links> |
|
116 <link href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita"><linktext>Video Player |
|
117 2 Tutorial</linktext></link> |
|
118 <link href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita"><linktext>Writing a |
|
119 Controller Plug-in</linktext></link> |
|
120 </related-links></task> |