<?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 xml:lang="en" id="GUID-D38456FB-BAA2-5473-B669-F44D5627155B"><title>Video Player 2 Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to play video data on graphics surfaces using the Video Client APIs. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to open, configure and play video clips on graphics surfaces. </p> <p><b>Required Background</b> </p> <p>The <xref href="GUID-2DC80BA9-7AA2-5CD3-9105-1DE28CE196C1.dita">Video Client Overview</xref> introduces the video client utilities. </p> <p><b>Introduction</b> </p> <p>The video player utility 2 enables you to open and play video data on graphics surfaces. For more information about graphics surfaces, see <xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">Graphics Surfaces</xref>. </p> <p>You can also render video to graphics surfaces without associating them with a target window. This allows you to use graphics surfaces provided by the Multimedia Framework (MMF), as well as other graphics surfaces where no window can be provided. </p> <p>This functionality is exposed by the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref> class. <codeph>CVideoPlayerUtility2</codeph> is derived from <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility</apiname></xref>. For more information about <codeph>CVideoPlayerUtility</codeph>, see the video player utility tutorials starting with <xref href="GUID-172F46C1-6066-57FA-A815-5AC23ACE159D.dita">Creating and Preparing a Video Player Tutorial</xref>. </p> <p> <b>Note:</b>  <codeph>CVideoPlayerUtility2</codeph> can only be used with controllers that support graphics surfaces. </p> </section> <section><title>Using Video Player 2 </title> <p>The following tasks are covered in this tutorial: </p> <ul><li id="GUID-2618FB7A-9DA7-5668-A38B-7BA1AFF7D1CE"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-6096635D-2793-5472-BC9E-101D7F7A167E">Constructing a utility object</xref>  </p> </li> <li id="GUID-67BB891B-8EA5-59EC-B115-0A691E6404F0"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-28CBE4D2-2979-5E2B-B707-9EB9BC051CC8">Opening a video source</xref>  </p> </li> <li id="GUID-C21D3851-F85B-58F0-A06C-CDD2E240C311"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-C984C913-6647-50E6-A30D-CAA41E6EE1B0">Adding a display</xref>  </p> </li> <li id="GUID-ED0F2F72-6476-5823-9712-D6CFE6A20367"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-3DBD0CE2-3351-5ED5-AB26-4976848E3B39">Preparing to play video data</xref>  </p> </li> <li id="GUID-410F168C-708B-5223-A8F4-95A1FB72B2C2"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-87F516DC-090E-57F9-B140-B4702F44E391">Making configuration adjustments</xref>  </p> </li> <li id="GUID-DB5EB16B-DD71-58DA-B0CB-419D1D4D33D4"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-6D7BD5B1-DDD0-5963-AF84-8169BD4D6CC3">Playing video data</xref>  </p> </li> <li id="GUID-2B5A7AFD-EF70-5D5D-8F7F-368C67476181"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-97516B18-D59B-5FA2-9881-2FE3025AE888">Replacing a surface</xref>  </p> </li> <li id="GUID-50F342B4-28D2-5734-9C14-2AE7474FA052"><p><xref href="GUID-D38456FB-BAA2-5473-B669-F44D5627155B.dita#GUID-D38456FB-BAA2-5473-B669-F44D5627155B/GUID-FB26B528-1FBB-5A6E-B33B-7368A9596DAF">Stopping video playback</xref>  </p> </li> </ul> <p id="GUID-6096635D-2793-5472-BC9E-101D7F7A167E"><b>Constructing a Utility Object</b> </p> <p>The high level step to construct a utility object is shown here: </p> <ul><li id="GUID-D52BCA9D-75A5-5DE5-9C19-8275E1529131"><p>To create a new instance of <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>, use the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>NewL()</apiname></xref> function: </p> <codeblock id="GUID-FD8FEFCC-49ED-59F4-9DF4-AAFA81B8CC6F" xml:space="preserve">NewL(MVideoPlayerUtilityObserver&amp; aObserver, TInt aPriority, TMdaPriorityPreference aPref);</codeblock> <p>Creating an instance of <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref> is similar to creating an instance of <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility</apiname></xref>, however, unlike the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility::NewL()</apiname></xref>, the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::NewL()</apiname></xref> method doesn’t take a window destination. </p> </li> </ul> <p id="GUID-28CBE4D2-2979-5E2B-B707-9EB9BC051CC8"><b>Opening a Video Source</b> </p> <p>Once created, the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref> needs to know what data it should be playing. </p> <p> <b>Note:</b> To open a video source with <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>, the controller must support graphics surfaces, otherwise it will fail with <codeph>KErrNotSupported</codeph>. </p> <p>Video clips must be opened using one of the following open functions: </p> <ul><li id="GUID-DE36678D-2B5F-5A67-B94B-CB02A002A756"><p> <b>From a file </b>  </p> <codeblock id="GUID-0F42B9CD-29F9-50A9-A617-D2683D139299" xml:space="preserve">OpenFileL(const TDesC&amp; aFileName, TUid aControllerUid=KNullUid);

</codeblock> <p>This method opens the video clip from a file. It uses an optionally specified plug-in in the argument to load a controller. If no controller plug-in is specified, it searches through the list of available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> <p> <b>Note:</b> There is also another method to open a video clip from a file. It is strongly recommended to use this method. </p> <codeblock id="GUID-C708A76D-0156-5106-B288-BFF6563A15F8" xml:space="preserve">OpenFileL(const TMMSource&amp; aSource, TUid aControllerUid);</codeblock> <p>Where <codeph>aSource</codeph> is a filename or an open handle to a file containing the video clip and <codeph>aControllerUid</codeph> is an optionally specified plug-in. If specified, it will force the video player to use the controller with the given UID. If no controller plug-in is specified, this function searches through a list of all available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> </li> <li id="GUID-E6A42E5B-685A-54FD-B6D0-B9ABED940F63"><p> <b>From a descriptor</b>  </p> <codeblock id="GUID-E53E70E6-FD54-5AB8-AC5D-F1EA6F86A9C6" xml:space="preserve">OpenDesL(const TDesC8&amp; aDescriptor, TUid aControllerUid=KNullUid);</codeblock> <p>This method opens the video clip from a descriptor. It opens the video clip contained as binary data in a descriptor using an optionally specified plug-in in the argument to load a controller. If no controller is specified, it searches through the list of available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> </li> <li id="GUID-01F9EE80-BBA3-5E92-A14D-E749003D332C"><p> <b>From an URL</b>  </p> <codeblock id="GUID-4C942ECA-1308-597B-8F6A-BE942222D53A" xml:space="preserve">OpenUrlL(const TDesC&amp; aUrl, TInt aIapId = KUseDefaultIap, const TDesC8&amp; aMimeType=KNullDesC8, TUid aControllerUid=KNullUid);</codeblock> <p>This method opens the video clip from the specified URL and identified by the MIME type. In addition a plug-in can be specified if necessary. If no controller plug-in is specified, this function searches through a list of all available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> </li> </ul> <p>Once the opening of the video clip is complete, successfully or otherwise, the callback function <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MVideoPlayerUtilityObserver::MvpuoOpenComplete()</apiname></xref> is called. This notifies the client whether the video clip was successfully opened or not. </p> <p> <b>Note:</b> Opening a video source must be done before providing any window destination. This is because the controller needs to be able to support graphics surfaces and this is only known at load time. </p> <p id="GUID-C984C913-6647-50E6-A30D-CAA41E6EE1B0"><b>Adding a Display</b> </p> <p>To play video on graphics surfaces without an associated target window you need to add a display. The high level steps to add a specified display are shown here: </p> <ul><li id="GUID-C7295586-EDEB-5DF3-A02F-B1CF5DE12215"><p>Call the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayL()</apiname></xref> method. This method takes a window server session, which is used to register the graphics surface, the display ID of the display that the surface is to be placed on, and a reference to a surface event handler. </p> <codeblock id="GUID-58633CE4-34E0-5780-8D13-A94B9CBA13EE" xml:space="preserve">IMPORT_C void AddDisplayL(RWsSession&amp; aWs, TInt aDisplay, MMMFSurfaceEventHandler&amp; aEventHandler);</codeblock> <p> <b>Note</b>: To use windowless graphics surfaces, you must provide an implementation of the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MMMFSurfaceEventHandler</apiname></xref> interface. The <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MMMFSurfaceEventHandler</apiname></xref> interface handles surface-related events from the MMF. </p> </li> </ul> <p id="GUID-3DBD0CE2-3351-5ED5-AB26-4976848E3B39"><b>Preparing to Play Video Data</b> </p> <p>The high level steps to prepare to play video are shown here: </p> <ol id="GUID-344888A8-4F8A-5481-8252-37E181FC1BEF"><li id="GUID-8E6DDFD9-583B-5B51-A3FF-15F567F5C743"><p>Once the video data is ready, call the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::Prepare()</apiname></xref> function. </p> </li> <li id="GUID-17137AFF-1E24-5A0D-9DD9-19B353A4209E"><p>When the client receives the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MVideoPlayerUtilityObserver::MvpuoPrepareComplete()</apiname></xref> callback, the video player utility will be in configured state. </p> </li> </ol> <p id="GUID-87F516DC-090E-57F9-B140-B4702F44E391"><b>Making Configuration Adjustments</b> </p> <p>Once the video clip is open and ready to play, configuration adjustments can be made using the following functions: </p> <ul><li id="GUID-E379C3CD-6117-53B9-BF0F-E78303D1A618"><p> <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayWindowL</apiname></xref>: This function adds a new window for displaying the video picture. Client applications must use this method instead of <codeph>SetDisplayWindowL()</codeph> when using <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>. This method has two overloads: </p> <ul><li id="GUID-C3098C44-63D5-56C3-9568-0BB5DE2EF41D"><p>The first takes window clipping and video extent as parameters: </p> <codeblock id="GUID-9F0B2B54-F376-5B3A-B2C5-C07E070496AC" xml:space="preserve">AddDisplayWindowL(RWsSession&amp; aWs, CWsScreenDevice&amp; aScreenDevice, RWindowBase&amp; aWindow, const TRect&amp; aVideoExtent, const TRect&amp; aWindowClipRect);</codeblock> </li> <li id="GUID-B9F7DDF9-A2CF-5249-85A4-1F62ED831637"><p>The second is a simplified version which doesn't take window clipping and video extent as parameters: </p> <codeblock id="GUID-5EACD930-7DA3-5FCB-8C16-5F1EDD04F9C4" xml:space="preserve">AddDisplayWindowL(RWsSession&amp; aWs, CWsScreenDevice&amp; aScreenDevice, RWindowBase&amp; aWindow);</codeblock> <p> <b>Note:</b> When using this version, the video extent and window clipping rectangle default to the whole window. </p> </li> </ul> </li> <li id="GUID-B6ECCA94-FA08-539C-BF86-8684BB34E972"><p> <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::SetVideoExtentL</apiname></xref>: This function sets the video extent on the screen, relative to the window. The extent specifies the area of screen in which the video picture is placed and may be partially or completely outside of the video window. Video picture position within the extent depends on the picture size and content alignment or offset. </p> <codeblock id="GUID-02EDD632-ED30-50B9-B4F3-11A304FDF75C" xml:space="preserve">SetVideoExtentL(const TRect&amp; aVideoExtent);</codeblock> <p> <b>Note:</b> Video extent can be set before a successful call to <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>AddDisplayWindowL</apiname></xref> has been made. </p> </li> <li id="GUID-155740FA-08F7-5429-A2EE-B912D467EF64"><p> <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::SetWindowClipRectL</apiname></xref>: This function sets the window clipping rectangle, relative to the window. The clipping rectangle specifies the part of the window used to display the video picture and must be fully contained within the window. Any video content falling outside of this area is not displayed. </p> <codeblock id="GUID-F360165D-1E13-5ABE-8D2E-3818B32B139C" xml:space="preserve">SetWindowClipRectL(const TRect&amp; aWindowClipRect);</codeblock> </li> </ul> <p id="GUID-6D7BD5B1-DDD0-5963-AF84-8169BD4D6CC3"><b>Playing Video Data</b> </p> <p>The high level step to play video data is shown here: </p> <ul><li id="GUID-89BDC30D-CE13-5A9C-B348-AA46D751B80A"><p>After configuring the properties, the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::Play()</apiname></xref> function is called for the video clip to be played. </p> </li> </ul> <p id="GUID-97516B18-D59B-5FA2-9881-2FE3025AE888"><b>Replacing a Surface</b> </p> <p>If <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CMMFVideoPlayerUtility2</apiname></xref> receives a <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>ReplaceSurface</apiname></xref> event, then the graphics surface needs to be replaced. The high level steps to replace a surface are shown here: </p> <ol id="GUID-A1A1CEE4-775E-5A3B-81FC-FAC2C6A6AEDF"><li id="GUID-24FB37D7-FC3A-57B8-AF88-2A01450BA623"><p>Call <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::RemoveDisplay()</apiname></xref> and set <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>aDisplay</apiname></xref> to be the ID of the display to remove. </p> <codeblock id="GUID-91A4F673-DE4A-5A78-976F-B90D4D1136F1" xml:space="preserve">IMPORT_C void RemoveDisplay(TInt aDisplay);</codeblock> </li> <li id="GUID-216C4BF6-809F-50C7-BCE5-704C15692A92"><p>Call <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayL()</apiname></xref>. This method takes a window server session, which is used to register the graphics surface, the display ID of the display that the surface is to be placed on, and a reference to a surface event handler. </p> <codeblock id="GUID-3B6FFFA5-0EA7-51B6-840E-BB3174F07662" xml:space="preserve">IMPORT_C void AddDisplayL(RWsSession&amp; aWs, TInt aDisplay, MMMFSurfaceEventHandler&amp; aEventHandler);</codeblock> </li> </ol> <p id="GUID-FB26B528-1FBB-5A6E-B33B-7368A9596DAF"><b>Stopping Video Playback</b> </p> <p>The high level steps to stop video playback are shown here: </p> <ol id="GUID-4D4C9ACD-1BDE-5F65-A1A7-3603EB87C6E1"><li id="GUID-1C696A16-E514-50C0-BFB1-BB55ADC21299"><p>Call the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::Stop()</apiname></xref> function. </p> <codeblock id="GUID-C2275FD7-7AAF-5D7E-9736-855BE9BAC2BE" xml:space="preserve">IMPORT_C TInt Stop();</codeblock> <p>Video playback is stopped as soon as possible, and the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MVideoPlayerUtilityObserver::MvpuoPlayComplete()</apiname></xref> callback function is called. </p> </li> <li id="GUID-46E456E9-71A5-531D-BA40-47AB20106263"><p>To remove a display from the list of surface rendering targets, call <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::RemoveDisplay()</apiname></xref> and set <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>aDisplay</apiname></xref> to be the ID of the display to remove: </p> <codeblock id="GUID-96BD89C8-0DFE-5D24-AD74-6BC8A893794C" xml:space="preserve">IMPORT_C void RemoveDisplay(TInt aDisplay);</codeblock> <p>Calling <codeph>RemoveDisplay()</codeph> destroys any graphics surface associated with the display. You must make sure the graphics surface can be safely destroyed before making this call. </p> <p> <b>Note</b>: If you have added windows to the display using <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayWindowL()</apiname></xref>, then the graphics surface can only be destroyed when you have removed all of the windows as well. That is, when no windows or event handlers are using the display. To remove a window, use the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::RemoveDisplayWindowL()</apiname></xref> function. </p> </li> </ol> </section> <section><title>See Also</title> <p><xref href="GUID-3F0856D9-7B58-5519-9B26-97F1A035E21D.dita">Video Player Utility Tutorials</xref>  </p> </section> </conbody></concept>